agent-accelerator 0.5.3 → 0.5.5

package/src/scheduler/scheduler.ts

@@ -14,14 +14,15 @@
  */
 import type { Agent } from "../agent/agent.ts";
 import { createChildSessionId } from "../agent/delegation.ts";
-import { buildDynamicWorkerConfig, grantWorkerTools, normalizeWorkerTimeoutValue } from "../agent/worker.ts";
+import { buildDynamicWorkerConfig, grantWorkerTools, scheduledRunTimeoutMs } from "../agent/worker.ts";
 import { telemetryBus } from "../telemetry.ts";
+import { readUsage, usageLine, type UsageTotals } from "../session/usage.ts";
 import { lockFolder } from "../utils/durable.ts";
 import { ConfigError, ValidationError } from "../types/errors.ts";
 import type { ToolDefinition } from "../types/tool.ts";
 import type { AgentResponse } from "../types/response.ts";
 import type {
-  KillResult,
+  DeleteResult,
   ScheduledActionInput,
   ScheduledActionPatch,
   ScheduledActionRecord,
@@ -68,16 +69,43 @@ export interface HomeOptions {
 }
 
 type PoolTools = Record<string, ToolDefinition>;
-type Outcome = { res: AgentResponse } | { error: string };
+type Outcome = ({ res: AgentResponse } | { error: string }) & { usage?: UsageTotals };
 interface RunningEntry {
-  /** Aborted by `kill`; every attempt of the run listens to it. */
+  /** Aborted by `delete`; every attempt of the run listens to it. */
   controller: AbortController;
   done: Promise<void>;
-  killed: boolean;
+  deleted: boolean;
+  /** Started by `run_now` or `onMissed: "run"`: due when it finishes. */
+  manual: boolean;
+  /** A manual run that replaces a missed occurrence: always `late`. A plain `run_now` is never late. */
+  missed: boolean;
 }
 
 const errText = (err: unknown): string => (err instanceof Error ? err.message : String(err));
 
+// A run's exact spending as run-header fields, the numbers `usageReport()` keeps for workers (tokens split, cache hit rate, cost and where the price came from); in: the one-shot worker's totals over all attempts, out: finish's RunHeader.
+function usageFields(totals: UsageTotals | undefined): Partial<RunHeader> {
+  if (!totals || totals.turns === 0) return {};
+  const u = usageLine(totals);
+  return {
+    turns: u.turns,
+    tokens: u.tokens.total,
+    inputTokens: u.tokens.input,
+    freshInputTokens: u.tokens.freshInput,
+    cacheReadTokens: u.tokens.cacheRead,
+    cacheWriteTokens: u.tokens.cacheWrite,
+    outputTokens: u.tokens.output,
+    thinkingTokens: u.tokens.thinking,
+    ...(u.cacheHitRate !== null ? { cacheHitRate: Math.round(u.cacheHitRate * 10_000) / 10_000 } : {}),
+    costUsd: u.cost.totalUsd === null ? "unknown" : Number(u.cost.totalUsd.toFixed(6)),
+    costSource: u.cost.source,
+    ...(u.cost.unpricedTurns > 0 ? { unpricedTurns: u.cost.unpricedTurns } : {}),
+  };
+}
+
+// Whole seconds since the epoch: stored times have no milliseconds, so lateness is compared at this precision; in: a clock reading or stored time, out: finish and deliver.
+const secondOf = (d: Date): number => Math.floor(d.getTime() / 1000);
+
 function emit(code: string, message: string, data: Record<string, unknown>, level: "info" | "warn" = "info"): void {
   telemetryBus.emit({ code: `scheduled_action.${code}`, message: `[Agent Accelerator] ${message}`, level, data });
 }
@@ -141,6 +169,9 @@ function checkSchedule(
   if (sa.retries !== undefined && !(Number.isInteger(sa.retries) && sa.retries >= 0)) {
     problems.push("scheduled_action.retries: must be a whole number >= 0.");
   }
+  if (sa.onMissed !== undefined && sa.onMissed !== "skip" && sa.onMissed !== "run") {
+    problems.push(`scheduled_action.onMissed: must be "skip" or "run" (omit it to decide later with run_now or skip); got ${JSON.stringify(sa.onMissed)}.`);
+  }
 }
 
 function checkOptionalFields(input: Pick<ScheduledActionPatch, "role" | "tools" | "timeoutMs">, pool: PoolTools | undefined, problems: string[]): void {
@@ -227,7 +258,7 @@ export class Scheduler {
         this.swept = true;
         this.startupSweep(now);
       }
-      this.deliverDue(now, first);
+      this.deliverDue(now);
       this.startDue(now);
       if (!this.hasPending()) this.stop();
     } catch (err) {
@@ -277,7 +308,7 @@ export class Scheduler {
     for (const t of this.snapshot().live) {
       if (t.state === "cooking") this.recoverCooking(t);
       else if (t.state === "waiting" && t.nextDeliverAt && parseLocalIso(t.nextDeliverAt).getTime() <= now.getTime()) {
-        this.markMissed(t.id, "process_down");
+        this.markMissed(t.id, "process_down", t.schedule.onMissed);
       }
     }
   }
@@ -288,7 +319,7 @@ export class Scheduler {
     const file = findRunFile(this.home, t.id, parseLocalIso(current.deliverAt), current.cookStartedAt);
     const run = file ? readRun(this.home, file) : undefined;
     if (!file || !run) {
-      this.markMissed(t.id, "interrupted");
+      this.markMissed(t.id, "interrupted", t.schedule.onMissed);
       return;
     }
     updateDeliveries(this.home, (pending) => {
@@ -299,6 +330,7 @@ export class Scheduler {
         status: run.header["status"] === "failed" ? "failed" : "ok",
         readyAt: run.header["finishedAt"] ?? current.deliverAt,
         deliverAt: current.deliverAt,
+        ...(run.header["late"] === "true" ? { late: true } : {}),
       });
     });
     updateTasks(this.home, (tasks) => {
@@ -309,7 +341,8 @@ export class Scheduler {
     });
   }
 
-  private markMissed(id: string, reason: string): void {
+  // Marks a run whose moment passed as missed, then applies the action's onMissed policy: `skip` moves on to the next time, `run` runs it now, unset waits for run_now / skip; in: the startup sweep, out: tasks.json + the missed (and skipped / started) events.
+  private markMissed(id: string, reason: string, policy?: "skip" | "run"): void {
     let name = id;
     updateTasks(this.home, (tasks) => {
       const t = tasks.find((x) => x.id === id);
@@ -318,25 +351,28 @@ export class Scheduler {
       t.state = "missed";
       delete t.current;
     });
-    emit("missed", `"${name}" (${id}) missed its run (${reason}). Use run_now or skip.`, { id, name, reason }, "warn");
+    const next = policy === "skip" ? "Skipping it (onMissed: skip)." : policy === "run" ? "Running it now (onMissed: run)." : "Use run_now or skip.";
+    emit("missed", `"${name}" (${id}) missed its run (${reason}). ${next}`, { id, name, reason, ...(policy ? { onMissed: policy } : {}) }, "warn");
+    if (policy === "skip") this.skip(id);
+    else if (policy === "run") this.startCook(id, true);
   }
 
   // ----- delivery ----------------------------------------------------------
 
-  private deliverDue(now: Date, first: boolean): void {
+  private deliverDue(now: Date): void {
     for (const entry of this.snapshot().pending) {
-      if (parseLocalIso(entry.deliverAt).getTime() <= now.getTime()) this.deliver(entry, now, first);
+      if (parseLocalIso(entry.deliverAt).getTime() <= now.getTime()) this.deliver(entry, now);
     }
   }
 
-  /** Removes the entry, records `lastRun`, THEN emits (whether or not anyone listens). */
-  private deliver(entry: PendingDelivery, now: Date, first: boolean): void {
+  // Removes the entry, records `lastRun`, THEN emits (whether or not anyone listens); late = it replaced a missed occurrence, was delivered over two ticks after its time, or finished after it; in: deliverDue, out: tasks.json + the delivered event.
+  private deliver(entry: PendingDelivery, now: Date): void {
     updateDeliveries(this.home, (pending) => {
       const i = pending.findIndex((p) => p.id === entry.id && p.file === entry.file);
       if (i >= 0) pending.splice(i, 1);
     });
     const deliverAt = parseLocalIso(entry.deliverAt).getTime();
-    const late = first || now.getTime() - deliverAt > 2 * this.tickMs || parseLocalIso(entry.readyAt).getTime() > deliverAt;
+    const late = entry.late === true || now.getTime() - deliverAt > 2 * this.tickMs || parseLocalIso(entry.readyAt).getTime() > deliverAt;
     let name = entry.id;
     updateTasks(this.home, (tasks) => {
       const t = tasks.find((x) => x.id === entry.id);
@@ -382,7 +418,7 @@ export class Scheduler {
    */
   private startCook(id: string, manual: boolean): ScheduledActionRecord | undefined {
     const now = this.now();
-    const ctx: { agent?: Agent; noAgent?: boolean } = {};
+    const ctx: { agent?: Agent; noAgent?: boolean; replacesMissed?: boolean } = {};
     const started = updateTasks(this.home, (tasks) => {
       const t = tasks.find((x) => x.id === id);
       if (!t) return undefined;
@@ -392,6 +428,7 @@ export class Scheduler {
         return undefined;
       }
       if (t.state === "cooking") return undefined;
+      ctx.replacesMissed = manual && t.state === "missed";
       ctx.agent = this.agents.get(t.agent)?.deref();
       if (!ctx.agent) {
         t.state = "missed";
@@ -427,7 +464,7 @@ export class Scheduler {
       cookStartedAt: started.current!.cookStartedAt,
       deliverAt: started.current!.deliverAt,
     });
-    this.launch(started, ctx.agent);
+    this.launch(started, ctx.agent, manual, ctx.replacesMissed === true);
     return started;
   }
 
@@ -458,8 +495,9 @@ export class Scheduler {
     }
   }
 
-  private launch(task: ScheduledActionRecord, agent: Agent): void {
-    const entry: RunningEntry = { controller: new AbortController(), done: Promise.resolve(), killed: false };
+  // Starts one run without awaiting it and tracks it until it ends; in: startCook, out: this.running + the run's files.
+  private launch(task: ScheduledActionRecord, agent: Agent, manual: boolean, missed: boolean): void {
+    const entry: RunningEntry = { controller: new AbortController(), done: Promise.resolve(), deleted: false, manual, missed };
     this.running.set(task.id, entry);
     entry.done = this.runWorker(task, agent, entry)
       .catch((err) => {
@@ -476,8 +514,8 @@ export class Scheduler {
   private async runWorker(task: ScheduledActionRecord, agent: Agent, entry: RunningEntry): Promise<void> {
     const deliverAt = parseLocalIso(task.current!.deliverAt);
     const outcome = await this.execute(task, agent, entry, deliverAt);
-    if (entry.killed) return; // killed: no run file, nothing delivered
-    this.finish(task, outcome, task.current!.cookStartedAt, deliverAt);
+    if (entry.deleted) return; // deleted: no run file, nothing delivered
+    this.finish(task, outcome, task.current!.cookStartedAt, deliverAt, entry);
   }
 
   /** A fresh stateless worker built from the saved fields; retries only while there is time before delivery. */
@@ -502,13 +540,13 @@ export class Scheduler {
       const attempts = 1 + (task.schedule.retries ?? 0);
       for (let attempt = 1; ; attempt++) {
         try {
-          return { res: await this.attempt(worker, task, agent, entry) };
+          return { res: await this.attempt(worker, task, agent, entry), usage: readUsage(worker.usageTotals) };
         } catch (err) {
-          if (entry.killed || attempt >= attempts || this.now().getTime() >= deliverAt.getTime()) throw err;
+          if (entry.deleted || attempt >= attempts || this.now().getTime() >= deliverAt.getTime()) throw err;
         }
       }
     } catch (err) {
-      return { error: errText(err) };
+      return { error: errText(err), ...(worker ? { usage: readUsage(worker.usageTotals) } : {}) };
     } finally {
       try {
         worker?.reset();
@@ -519,14 +557,14 @@ export class Scheduler {
   }
 
   private async attempt(worker: Agent, task: ScheduledActionRecord, agent: Agent, entry: RunningEntry): Promise<AgentResponse> {
-    const ms = normalizeWorkerTimeoutValue(agent.dynamicSubagents?.timeout ?? 0, task.timeoutMs);
-    // One controller per attempt (the timeout is per attempt), fed by the entry's kill controller.
+    const ms = scheduledRunTimeoutMs(agent.dynamicSubagents?.workerTimeoutMs ?? Infinity, task.timeoutMs);
+    // One controller per attempt (the timeout is per attempt), fed by the entry's delete controller.
     const controller = new AbortController();
-    const kill = () => controller.abort(entry.controller.signal.reason ?? new Error("killed"));
-    if (entry.controller.signal.aborted) kill();
-    else entry.controller.signal.addEventListener("abort", kill, { once: true });
+    const onDelete = () => controller.abort(entry.controller.signal.reason ?? new Error("deleted"));
+    if (entry.controller.signal.aborted) onDelete();
+    else entry.controller.signal.addEventListener("abort", onDelete, { once: true });
     const timer = ms > 0 ? setTimeout(() => controller.abort(new Error(`timed out after ${ms}ms`)), ms) : undefined;
-    // Raced so a timeout or kill ends the attempt even if the provider ignores the signal.
+    // Raced so a timeout or delete ends the attempt even if the provider ignores the signal.
     const aborted = new Promise<never>((_, reject) => {
       controller.signal.addEventListener("abort", () => reject(controller.signal.reason ?? new Error("aborted")), { once: true });
     });
@@ -534,35 +572,33 @@ export class Scheduler {
       return await Promise.race([worker.run(task.task, { signal: controller.signal }), aborted]);
     } finally {
       clearTimeout(timer);
-      entry.controller.signal.removeEventListener("abort", kill);
+      entry.controller.signal.removeEventListener("abort", onDelete);
     }
   }
 
-  /** Write order: run file, then the `deliveries.json` entry, then `tasks.json`. A crash in between is repaired on start. */
-  private finish(task: ScheduledActionRecord, outcome: Outcome, startedAt: string, deliverAt: Date): void {
+  // Writes a finished run: run file, then the `deliveries.json` entry, then `tasks.json` (a crash in between is repaired on start); a manual run is due when it finishes and is late only if it replaced a missed occurrence, a scheduled one is late only past its second; in: runWorker, out: the files and the ready/failed event.
+  private finish(task: ScheduledActionRecord, outcome: Outcome, startedAt: string, deliverAt: Date, run: Pick<RunningEntry, "manual" | "missed">): void {
     const now = this.now();
     const ok = "res" in outcome;
     const finishedAt = toLocalIso(now);
+    const due = run.manual ? now : deliverAt;
+    const late = run.missed || secondOf(now) > secondOf(due);
     const header: RunHeader = {
       id: task.id,
       name: task.name,
       status: ok ? "ok" : "failed",
       startedAt,
       finishedAt,
-      deliverAt: toLocalIso(deliverAt),
-      late: now.getTime() > deliverAt.getTime(),
-      ...(ok
-        ? {
-            model: `${outcome.res.provider}/${outcome.res.model}`,
-            tokens: outcome.res.usage.totalTokens,
-            costUsd: outcome.res.usage.cost?.totalCost ?? "unknown",
-          }
-        : { error: outcome.error }),
+      deliverAt: toLocalIso(due),
+      late,
+      ...(ok ? { model: `${outcome.res.provider}/${outcome.res.model}` } : {}),
+      ...usageFields(outcome.usage),
+      ...(ok ? {} : { error: outcome.error }),
     };
     const body = ok ? outcome.res.text.trim() || "[The worker returned no text.]" : `The run failed: ${outcome.error}`;
     const file = writeRunFile(this.home, task.id, deliverAt, header, body);
     updateDeliveries(this.home, (pending) => {
-      pending.push({ id: task.id, file, status: header.status, readyAt: finishedAt, deliverAt: header.deliverAt });
+      pending.push({ id: task.id, file, status: header.status, readyAt: finishedAt, deliverAt: header.deliverAt, ...(run.missed ? { late: true } : {}) });
     });
     updateTasks(this.home, (tasks) => {
       const t = tasks.find((x) => x.id === task.id);
@@ -611,7 +647,7 @@ export class Scheduler {
     return rec;
   }
 
-  async kill(id: string, opts: { force?: boolean; purge?: boolean }): Promise<KillResult> {
+  async delete(id: string, opts: { force?: boolean; purge?: boolean }): Promise<DeleteResult> {
     const rec = readTasks(this.home).find((t) => t.id === id);
     if (!rec) return { ok: false, reason: "not_found" };
     const run = this.running.get(id);
@@ -619,12 +655,12 @@ export class Scheduler {
       return {
         ok: false,
         reason: "running",
-        message: `"${id}" is cooking right now, so nothing was changed. Ask the user whether to abort it; if they agree, call kill again with force: true.`,
+        message: `"${id}" is cooking right now, so nothing was changed. Ask the user whether to abort it; if they agree, call delete again with force: true.`,
       };
     }
     if (run) {
-      run.killed = true;
-      run.controller.abort(new Error("killed"));
+      run.deleted = true;
+      run.controller.abort(new Error("deleted"));
       await run.done;
     }
     updateTasks(this.home, (tasks) => {
@@ -635,7 +671,7 @@ export class Scheduler {
       for (let i = pending.length - 1; i >= 0; i--) if (pending[i]!.id === id) pending.splice(i, 1);
     });
     if (opts.purge) removeTaskFolder(this.home, id);
-    emit("killed", `"${rec.name}" (${id}) was killed.`, { id, name: rec.name, forced: !!run, purged: !!opts.purge });
+    emit("deleted", `"${rec.name}" (${id}) was deleted.`, { id, name: rec.name, forced: !!run, purged: !!opts.purge });
     return { ok: true };
   }
 }
@@ -712,6 +748,7 @@ export function createScheduledAction(agent: Agent, input: ScheduledActionInput)
         startCookingInAdvance: lead,
         ...(sa.repeatEvery !== undefined ? { repeatEvery: sa.repeatEvery } : {}),
         ...(sa.retries !== undefined ? { retries: sa.retries } : {}),
+        ...(sa.onMissed !== undefined ? { onMissed: sa.onMissed } : {}),
       },
       state: "waiting",
       nextCookAt: toLocalIso(cookTime(deliverAt, durationMs(lead, "scheduled_action.startCookingInAdvance"))),
@@ -811,6 +848,6 @@ export function skipScheduledAction(id: string, opts?: HomeOptions): ScheduledAc
  * `force: true` (the run is aborted, then deleted). Past run files are kept
  * unless `purge: true`.
  */
-export function killScheduledAction(id: string, opts?: HomeOptions & { force?: boolean; purge?: boolean }): Promise<KillResult> {
-  return schedulerFor(opts).kill(id, { force: opts?.force, purge: opts?.purge });
+export function deleteScheduledAction(id: string, opts?: HomeOptions & { force?: boolean; purge?: boolean }): Promise<DeleteResult> {
+  return schedulerFor(opts).delete(id, { force: opts?.force, purge: opts?.purge });
 }

package/src/scheduler/store.ts

@@ -17,6 +17,7 @@ import { telemetryBus } from "../telemetry.ts";
 import { resolveHome } from "../utils/home.ts";
 export { resolveHome };
 import { ValidationError } from "../types/errors.ts";
+import type { CostSource } from "../session/usage.ts";
 import type { ScheduledActionRecord, ScheduledRunStatus } from "../types/scheduler.ts";
 import { durationMs, runFileName } from "./time.ts";
 
@@ -33,6 +34,8 @@ export interface PendingDelivery {
   status: ScheduledRunStatus;
   readyAt: string;
   deliverAt: string;
+  /** Set when the run replaced a missed occurrence: it is late whatever the clock says (a `run_now` on a `missed` action, or `onMissed: "run"`). */
+  late?: boolean;
 }
 
 /** Header written at the top of every run file. */
@@ -46,9 +49,26 @@ export interface RunHeader {
   /** The run finished after its delivery time. */
   late: boolean;
   model?: string;
+  /** Model calls the run made (all attempts), and what they spent: the same numbers `usageReport()` keeps for workers. */
+  turns?: number;
+  /** Input + output tokens. */
   tokens?: number;
-  /** `unknown` when the model has no known pricing (never a made-up 0). */
+  /** Everything sent; `freshInputTokens + cacheReadTokens + cacheWriteTokens`. */
+  inputTokens?: number;
+  freshInputTokens?: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+  /** Everything generated, thinking included. */
+  outputTokens?: number;
+  thinkingTokens?: number;
+  /** `cacheReadTokens / inputTokens`, 0 to 1; absent when nothing was sent. */
+  cacheHitRate?: number;
+  /** `unknown` when no turn had a known price (never a made-up 0). */
   costUsd?: number | "unknown";
+  /** Where the price came from: the `provider`'s reported cost, the `catalog`, `mixed`, or `unknown`. */
+  costSource?: CostSource;
+  /** Turns with no known price; when present, `costUsd` is a lower bound. */
+  unpricedTurns?: number;
   error?: string;
 }
 
@@ -163,6 +183,7 @@ const recordSchema = z
       startCookingInAdvance: z.string(),
       repeatEvery: z.string().optional(),
       retries: z.number().int().min(0).optional(),
+      onMissed: z.enum(["skip", "run"]).optional(),
     }),
     state: z.enum(["waiting", "cooking", "missed", "done"]),
     nextCookAt: iso.nullable(),
@@ -195,6 +216,7 @@ const deliverySchema = z.object({
   status: z.enum(["ok", "failed"]),
   readyAt: iso,
   deliverAt: iso,
+  late: z.boolean().optional(),
 });
 
 /** `undefined` when a `deliveries.json` entry is usable, else a one-line reason. Never throws. */

package/src/scheduler/tool.ts

@@ -14,7 +14,7 @@ import type { ScheduledActionInput, ScheduledActionPatch } from "../types/schedu
 import {
   createScheduledAction,
   getScheduler,
-  killScheduledAction,
+  deleteScheduledAction,
   listScheduledActions,
   runScheduledAction,
   skipScheduledAction,
@@ -24,7 +24,7 @@ import {
 import { readRun } from "./store.ts";
 import { formatDatetime } from "./time.ts";
 
-const COMMANDS = ["create", "list", "get", "update", "kill", "run_now", "skip"] as const;
+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. */
@@ -50,9 +50,10 @@ 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.'),
 });
 
-const describedId = "Full action id including its 6-character suffix (get, update, kill, run_now, skip).";
+const describedId = "Full action id including its 6-character suffix (get, update, delete, run_now, skip).";
 
 /** Builds the `scheduled_actions` tool for `agent`; its description is the manual with the worker pool filled in. */
 export function createScheduledActionsTool(agent: Agent): ToolDefinition {
@@ -85,10 +86,10 @@ export function createScheduledActionsTool(agent: Agent): ToolDefinition {
       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("Per-run time limit in ms (> 0)."),
+      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("kill: abort a run that is cooking. Ask the user first."),
-      purge: z.boolean().optional().describe("kill: also delete past run files."),
+      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."),
     }),
     execute: async (a) => {
       const sa = a.scheduled_action ?? {};
@@ -137,8 +138,8 @@ export function createScheduledActionsTool(agent: Agent): ToolDefinition {
           }
           return updateScheduledAction(id, patch, { home });
         }
-        case "kill":
-          return killScheduledAction(needId(), { home, force: a.force, purge: a.purge });
+        case "delete":
+          return deleteScheduledAction(needId(), { home, force: a.force, purge: a.purge });
         case "run_now":
           return runScheduledAction(needId(), { home });
         case "skip":

package/src/session/journal.ts

@@ -51,6 +51,8 @@ export class SessionJournal {
   private lastRun: unknown;
   /** JSON of the last journaled waiting prompts. */
   private pending = EMPTY_PENDING;
+  /** JSON of the last journaled spending totals. */
+  private usage = "";
   /** Run ids whose ending is on disk. */
   private readonly endsOnDisk = new Set<string>();
   /** How many of the current run's finished tool results are on disk, and the last one. */
@@ -90,6 +92,8 @@ export class SessionJournal {
     if (meta !== this.meta) records.push(`{"t":"meta","m":${meta}}`);
     const pending = this.pendingOf(agent);
     if (pending !== this.pending) records.push(`{"t":"pending","p":${pending}}`);
+    const usage = this.usageOf(agent);
+    if (usage !== this.usage) records.push(`{"t":"usage","u":${usage}}`);
     if (records.length === 0) return;
     const text = records.join("\n") + "\n";
     try {
@@ -110,6 +114,7 @@ export class SessionJournal {
     this.runCount = runs.length;
     this.lastRun = runs[runs.length - 1];
     this.pending = pending;
+    this.usage = usage;
     this.toolCount = tools.length;
     this.lastTool = tools[tools.length - 1];
     for (const mark of runs) if (mark.end) this.endsOnDisk.add(mark.id);
@@ -134,6 +139,7 @@ export class SessionJournal {
     writeFileDurable(path.join(this.dir, JOURNAL_FILE), header, { backup: false });
     this.epoch = epoch;
     this.pending = pending;
+    this.usage = this.usageOf(agent); // the snapshot holds it
     this.runs(agent);
     this.count = messages.length;
     this.last = messages[messages.length - 1];
@@ -167,9 +173,14 @@ export class SessionJournal {
     return JSON.stringify({ steer: slim(waiting.steer), queue: slim(waiting.queue) } satisfies SessionPending);
   }
 
+  // JSON of the agent's spending totals (`null` before its first model call); in: the live agent, out: change detection + the `usage` record.
+  private usageOf(agent: SessionAgentLike): string {
+    return agent.usageTotals && agent.usageTotals.turns > 0 ? JSON.stringify(agent.usageTotals) : "null";
+  }
+
   // 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, ...rest } = buildSessionData(
+    const { version: _v, sessionId: _s, messages: _m, totals: _t, runs: _r, usage: _u, ...rest } = buildSessionData(
       { ...agent, context: { ...agent.context, messages: [] } },
       null
     );

package/src/session/store.ts

@@ -33,6 +33,7 @@ import type { SubAgentStep } from "../types/response.ts";
 import { SessionLoadError } from "../types/errors.ts";
 import { createSessionId } from "../utils/session.ts";
 import { writeFileDurable, readWithBackup } from "../utils/durable.ts";
+import type { UsageTotals } from "./usage.ts";
 
 /** Cumulative per-session token + cost totals (JSON-safe). */
 export interface SessionTotals {
@@ -118,6 +119,8 @@ export interface PersistedAgentSession {
   epoch?: string;
   /** Where each run began, oldest first. */
   runs?: SessionRunMark[];
+  /** What this agent spent on its own model calls (see `usage.ts`); the journal keeps it current with `usage` records. */
+  usage?: UsageTotals;
   /** Read from the journal only (never in `session.json`): prompts that were still waiting. */
   pending?: SessionPending;
   /** Read from the journal only: results of tool calls finished in the current run (used to resume without repeating them). */
@@ -335,6 +338,8 @@ export interface SessionAgentLike {
   pendingPrompts?: () => SessionPending;
   /** Tool calls finished in the current run (cleared when the next run starts). */
   toolRecords?: SessionToolRecord[];
+  /** What this agent spent on its own model calls. */
+  usageTotals?: UsageTotals;
   context: { systemPrompt?: string; messages: Message[] };
 }
 
@@ -482,6 +487,7 @@ 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 } : {}),
   };
 }
 
@@ -671,6 +677,7 @@ function parseSession(raw: string, limits?: SessionLimits): PersistedAgentSessio
       subagents: obj.subagents,
       ...(typeof obj.epoch === "string" ? { epoch: obj.epoch } : {}),
       ...(Array.isArray(obj.runs) ? { runs: obj.runs as SessionRunMark[] } : {}),
+      ...(obj.usage && typeof obj.usage === "object" ? { usage: obj.usage as UsageTotals } : {}),
     };
   } catch {
     return null;
@@ -985,7 +992,7 @@ 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;
 
-// 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, `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.
+// 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 {
   if (!snapshot.epoch) return snapshot;
   const lines = text.split("\n");
@@ -997,7 +1004,7 @@ function replayJournal(snapshot: PersistedAgentSession, text: string, file: stri
   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; 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 };
     try {
       rec = JSON.parse(line);
     } catch {
@@ -1023,6 +1030,8 @@ function replayJournal(snapshot: PersistedAgentSession, text: string, file: stri
       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 } : {}) }];
+    } 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") {
       const p = rec.p as SessionPending; // latest record wins
       if (Array.isArray(p.steer) && Array.isArray(p.queue)) {
@@ -1328,15 +1337,16 @@ function toDollars(microUSD: number): number {
  * `cost.context_over_200k`, the over-200k tier prices apply; otherwise base
  * `pricing.*` (falling back to legacy `cost.*`) applies.
  */
+// Cache prices stay undefined when the catalog has none: priceUsage then bills those tokens at the input rate (never free).
 function resolveEffectivePricing(
   spec: ModelSpec | undefined,
   inputTokens: number
-): { input: number; output: number; cacheRead: number; cacheWrite: number; 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,
-    cacheRead: spec?.pricing?.cacheReadPerMillion ?? (spec?.cost?.cache_read as number | undefined) ?? 0,
-    cacheWrite: spec?.pricing?.cacheWritePerMillion ?? (spec?.cost?.cache_write as number | undefined) ?? 0,
+    cacheRead: spec?.pricing?.cacheReadPerMillion ?? (spec?.cost?.cache_read as number | undefined),
+    cacheWrite: spec?.pricing?.cacheWritePerMillion ?? (spec?.cost?.cache_write as number | undefined),
     audio:
       spec?.pricing?.inputAudioPerMillion ?? (spec?.cost as { input_audio?: number } | undefined)?.input_audio ?? 0,
   };
@@ -1388,8 +1398,9 @@ function resolveEffectivePricing(
  * - Audio tokens (`usage.audioTokens` / `usage.inputAudioTokens` when present)
  *   price at `pricing.inputAudioPerMillion` / `cost.input_audio` and fold into
  *   the total (separately itemized in `breakdown.audioMicroUSD`).
- * - `opts.serviceTier` (`flex` ~0.5x, `priority` ~1.5x, estimates) scales the
+ * - `opts.serviceTier` (`flex` 0.5x, `priority` 2x, estimates) scales the
  *   catalog total; provider-reported costs are never rescaled.
+ * - Cache reads and writes are subsets of the input tokens; a missing cache price bills at the input rate.
  */
 export function priceUsage(
   usage: TokenUsage,
@@ -1438,12 +1449,15 @@ export function priceUsage(
     return undefined;
   }
   const { multiplier, tier: serviceTier } = serviceTierMultiplier(opts?.serviceTier, opts?.modelId ?? spec?.id);
-  const nonCachedInput = Math.max(0, inputTokens - cachedTokens);
+  // Cache reads and writes are both a SUBSET of the input tokens (OpenRouter `prompt_tokens` includes them), so the
+  // plain input rate applies only to what is neither read from nor written to the cache.
+  const freshInput = Math.max(0, inputTokens - cachedTokens - cacheWriteTokens);
   // Integer micro-USD accumulation: microUSD = tokens * pricePerMillion
   // ($P per 1M tokens == $P/1e6 per token == P micro-USD per token).
-  const inputMicroUSD = Math.round(nonCachedInput * pricing.input * multiplier);
-  const cacheReadMicroUSD = Math.round(cachedTokens * pricing.cacheRead * multiplier);
-  const cacheWriteMicroUSD = Math.round(cacheWriteTokens * pricing.cacheWrite * multiplier);
+  // A catalog entry without a cache price bills those tokens at the input rate: cache reads/writes are never free.
+  const inputMicroUSD = Math.round(freshInput * pricing.input * multiplier);
+  const cacheReadMicroUSD = Math.round(cachedTokens * (pricing.cacheRead ?? pricing.input) * multiplier);
+  const cacheWriteMicroUSD = Math.round(cacheWriteTokens * (pricing.cacheWrite ?? pricing.input) * multiplier);
   const outputMicroUSD = Math.round(outputTokens * pricing.output * multiplier);
   const audioMicroUSD = Math.round(audioCount * pricing.audio * multiplier);
   const totalMicroUSD = inputMicroUSD + cacheReadMicroUSD + cacheWriteMicroUSD + outputMicroUSD + audioMicroUSD;