agent-accelerator 0.5.4 → 0.5.6

package/src/providers/shared.ts

@@ -9,6 +9,8 @@ import { toConciseProviderError } from "../utils/errors.ts";
 import { withRetries } from "../utils/retry.ts";
 import { redactHeadersCentral } from "../utils/cache.ts";
 import { TRUNCATED_ARGS_KEY, isTruncatedArguments } from "../types/tool.ts";
+import { SSEParser } from "../streaming/sse-parser.ts";
+import type { AssistantMessageEventStream } from "../streaming/event-stream.ts";
 
 /** Parses a JSON tool-argument string; non-objects degrade to the truncated-arguments marker. */
 export function parseArguments(raw: string | undefined): Record<string, unknown> {
@@ -43,17 +45,17 @@ export function redactedHeaders(headers: Record<string, string>): Record<string,
 }
 
 /**
- * Extracts `{ message, code, errorType, raw }` from a non-2xx JSON body. Handles
- * OpenAI `type`, OpenRouter `metadata.error_type` + `metadata.raw`, and Google
+ * Extracts `{ message, code, errorType, raw, limitSource }` from a non-2xx JSON body. Handles
+ * OpenAI `type`, OpenRouter `metadata.error_type` + `metadata.raw` + `metadata.limit_source`, and Google
  * `status` code shapes; unknown bodies degrade to a 300-char slice.
  */
 export function readErrorPayload(
   bodyText: string
-): { message: string; code?: string | number; errorType?: string; raw?: string } {
+): { message: string; code?: string | number; errorType?: string; raw?: string; limitSource?: string } {
   try {
     const parsed: unknown = JSON.parse(bodyText);
     const first = Array.isArray(parsed) ? parsed[0] : parsed;
-    const err = (first as { error?: { message?: string; code?: string | number; type?: string; status?: string | number; metadata?: { error_type?: string; raw?: unknown } } })?.error;
+    const err = (first as { error?: { message?: string; code?: string | number; type?: string; status?: string | number; metadata?: { error_type?: string; raw?: unknown; limit_source?: unknown } } })?.error;
     if (err && typeof err.message === "string") {
       const code = err.code ?? err.status;
       const errorType =
@@ -67,6 +69,7 @@ export function readErrorPayload(
         ...(code !== undefined ? { code } : {}),
         ...(typeof errorType === "string" ? { errorType } : {}),
         ...(raw ? { raw } : {}),
+        ...(typeof err.metadata?.limit_source === "string" ? { limitSource: err.metadata.limit_source } : {}),
       };
     }
     return { message: bodyText.slice(0, 300) };
@@ -135,11 +138,11 @@ export function combinedSignal(signal?: AbortSignal, timeoutMs?: number): { sign
   if (signal) {
     if (signal.aborted) {
       cleanup();
-      ctrl.abort();
+      ctrl.abort(signal.reason); // the caller's reason survives (`interrupt(new Error("..."))`)
     } else {
       signal.addEventListener("abort", () => {
         cleanup();
-        try { ctrl.abort(); } catch {}
+        try { ctrl.abort(signal.reason); } catch {}
       }, { once: true });
     }
   }
@@ -180,6 +183,12 @@ export function hasTruncatedToolArguments(args: unknown): boolean {
   return isTruncatedArguments(args);
 }
 
+// True when a stream with no terminal event left a tool call whose arguments never fully arrived (none at all, or cut mid-JSON); in: the adapter's assembled calls and their records, out: its incomplete_stream guard.
+export function hasUnfinishedToolCall(calls: Iterable<{ startArgs: string; deltaArgs: string }>, toolCalls: Array<{ arguments: unknown }>): boolean {
+  for (const c of calls) if (!c.startArgs.trim() && !c.deltaArgs.trim()) return true;
+  return toolCalls.some((c) => isTruncatedArguments(c.arguments));
+}
+
 /** Short hash for tool-ID clamping (FNV-1a, 8 hex chars, no deps). */
 export function shortHashId(value: string): string {
   let h = 0x811c9dc5;
@@ -198,7 +207,10 @@ export function shortHashId(value: string): string {
 export function clampToolCallId(id: string): string {
   const clean = String(id ?? "").replace(/[^a-zA-Z0-9_-]/g, "_");
   if (!clean.includes("|")) {
-    return clean.length > 40 ? clean.slice(0, 40) : clean || "call_unknown";
+    if (clean.length <= 40) return clean || "call_unknown";
+    // A hard cut would give two long ids with the same first 40 characters the same id; a hash of the whole id keeps them apart.
+    const hash = shortHashId(id);
+    return `${clean.slice(0, 40 - hash.length - 1)}_${hash}`;
   }
   const sep = clean.indexOf("|");
   const callId = clean.slice(0, sep).replace(/_+$/, "") || "call";
@@ -210,6 +222,16 @@ export function clampToolCallId(id: string): string {
   return `${prefix}_${hash}`;
 }
 
+// The finish reason of a turn that produced tool calls: `tool_calls`, except that a turn cut off by the output limit (`length`) keeps saying so when one of its calls was cut mid-JSON; in: the wire finish reason + the assembled calls, out: each streaming adapter.
+export function toolTurnFinishReason(finishReason: string, toolCalls: Array<{ arguments: unknown }>): string {
+  return finishReason === "length" && toolCalls.some((c) => isTruncatedArguments(c.arguments)) ? "length" : "tool_calls";
+}
+
+// The JSON text of a tool call's arguments for a history message: `{}` for a call whose streamed arguments were cut off (the internal `__truncated_raw` marker was never the model's own output and is never resent); in: a stored tool call, out: each adapter's history builder.
+export function toolArgumentsJson(args: unknown): string {
+  return isTruncatedArguments(args) ? "{}" : JSON.stringify(args || {});
+}
+
 /** Plain lower-cased header record from a fetch `Headers` object. */
 export function headersToRecord(headers: Headers): Record<string, string> {
   const out: Record<string, string> = {};
@@ -282,3 +304,110 @@ export function retryOptionsFrom(options: {
     retryBudgetMs: options?.retryBudgetMs,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Streaming scaffold shared by the SSE adapters (abort linking, request timer, read loop, end-of-stream check, failure)
+// ---------------------------------------------------------------------------
+
+// Ties a provider stream to the caller's signal and to the stream's own cancel: one controller that aborts when either does; in: an adapter's stream(), out: the controller its request uses and the `release` its finally block calls.
+export function linkStreamAbort(eventStream: AssistantMessageEventStream, signal: AbortSignal | undefined): { linked: AbortController; release: () => void } {
+  const linked = new AbortController();
+  const forwardUserAbort = (): void => {
+    try {
+      linked.abort((signal as { reason?: unknown } | undefined)?.reason);
+    } catch {
+      try {
+        linked.abort();
+      } catch {}
+    }
+  };
+  if (signal?.aborted) forwardUserAbort();
+  else signal?.addEventListener("abort", forwardUserAbort, { once: true });
+  const removeStreamCancel = eventStream.onCancel(() => {
+    try {
+      linked.abort();
+    } catch {}
+  });
+  return {
+    linked,
+    release: () => {
+      try {
+        signal?.removeEventListener("abort", forwardUserAbort);
+      } catch {}
+      try {
+        removeStreamCancel();
+      } catch {}
+    },
+  };
+}
+
+// Runs one request attempt under a timer that aborts `controller` after `ms` (none when unset); in: an adapter's fetchOnce, out: its Response.
+export async function withAbortTimer<T>(controller: AbortController, ms: number | undefined, run: () => Promise<T>): Promise<T> {
+  const timer =
+    ms && ms > 0
+      ? setTimeout(() => {
+          try {
+            controller.abort();
+          } catch {}
+        }, ms)
+      : undefined;
+  try {
+    return await run();
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+// Reads an SSE response body to its end, handing each `data:` payload to `onData`; stops with an AbortError as soon as the stream is aborted or cancelled (cancelling the body, whose rejection is absorbed); in: the opened Response body of an SSE adapter, out: calls to onData.
+export async function readSseData(
+  body: ReadableStream<Uint8Array>,
+  linked: AbortController,
+  eventStream: AssistantMessageEventStream,
+  onData: (data: string) => void
+): Promise<void> {
+  const parser = new SSEParser();
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  const abort = (): Error => Object.assign(new Error("Stream aborted"), { name: "AbortError" });
+  linked.signal.addEventListener("abort", () => void reader.cancel().catch(() => {}), { once: true }); // an aborted body is already errored: its cancel() rejects, and nobody else listens
+  while (true) {
+    if (linked.signal.aborted || eventStream.isCancelled()) {
+      try {
+        await reader.cancel();
+      } catch {}
+      throw abort();
+    }
+    const { done, value } = await reader.read();
+    if (done) break;
+    for (const m of parser.feed(decoder.decode(value, { stream: true }))) onData(m.data);
+  }
+  for (const m of parser.flush()) onData(m.data);
+  try {
+    reader.releaseLock();
+  } catch {}
+  if (linked.signal.aborted || eventStream.isCancelled()) throw abort();
+}
+
+// The error to fail with when an SSE stream ended without its final event while carrying no content or an unfinished tool call (checked only for real SSE payloads, not JSON mocks); in: the adapter's state after reading, out: `eventStream.fail`, else undefined.
+export function incompleteStreamCheck(a: {
+  provider: string;
+  modelId: string;
+  hasTerminal: boolean;
+  empty: boolean;
+  unfinishedCall: boolean;
+  responseHeaders: Record<string, string>;
+  framesSeen: number;
+  badFrames: number;
+}): Error | undefined {
+  if (a.hasTerminal || !(a.empty || a.unfinishedCall)) return undefined;
+  const contentType = Object.entries(a.responseHeaders).find(([k]) => k.toLowerCase() === "content-type")?.[1];
+  const isSSEPayload = (typeof contentType === "string" && (contentType.includes("event-stream") || contentType.startsWith("text/"))) || a.framesSeen > 0 || a.badFrames > 0;
+  return isSSEPayload ? incompleteStreamError(a.provider, a.modelId) : undefined;
+}
+
+// Fails a stream with the right error: an abort (the signal, the stream's cancel, or an AbortError) becomes the plain `AbortError`, anything else passes through; in: an adapter's catch block, out: the stream's result() rejection.
+export function failStream(eventStream: AssistantMessageEventStream, linked: AbortController, err: unknown): void {
+  const raw = err instanceof Error ? err : new Error(String(err));
+  const isAbort = linked.signal.aborted || eventStream.isCancelled() || (raw as { name?: string }).name === "AbortError";
+  eventStream.fail(isAbort ? Object.assign(new Error("Stream aborted"), { name: "AbortError" }) : raw);
+}

package/src/providers.ts

@@ -248,17 +248,17 @@ export function resolveCache(
   return undefined;
 }
 
-/** Warns once per provider/model that per-media `resolution` is ignored (no such control on that wire); in: an adapter's request messages, out: telemetry bus only. */
-export function warnIgnoredMediaResolution(provider: string, messages: Message[], modelRef: string): void {
+/** Warns once per provider/model that per-media `resolution` is ignored (no such control on that wire for the given kinds of media); in: an adapter's request messages, out: telemetry bus only. */
+export function warnIgnoredMediaResolution(provider: string, messages: Message[], modelRef: string, kinds: Array<"image" | "video"> = ["image", "video"]): void {
   const used = messages.some(
-    (m) => Array.isArray(m.content) && m.content.some((p) => (p.type === "image" || p.type === "video") && p.resolution)
+    (m) => Array.isArray(m.content) && m.content.some((p) => (p.type === "image" || p.type === "video") && kinds.includes(p.type) && p.resolution)
   );
   if (!used) return;
   emitProviderWarning({
     provider,
     capability: "media resolution",
     requested: modelRef,
-    reason: "this provider has no per-media detail control (Google only).",
+    reason: "this provider has no per-media detail control for this kind of media.",
     fallback: "the provider's default detail",
   });
 }
@@ -399,6 +399,7 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
  * @example `parseStreamedToolArguments("{}", '{"location":"Paris"}')`
  */
 export function parseStreamedToolArguments(startText: string, deltaText: string): Record<string, unknown> {
+  if (!startText.trim() && !deltaText.trim()) return {}; // no argument text at all is a call that takes none
   const candidates = [startText + deltaText, deltaText, startText].filter((c) => c && c.trim());
   for (const candidate of candidates) {
     try {
@@ -422,6 +423,7 @@ export function parseStreamedToolArguments(startText: string, deltaText: string)
  * @example `selectRawArguments("{}", '{"location":"Paris"}') // '{"location":"Paris"}'`
  */
 export function selectRawArguments(startText: string, deltaText: string): string {
+  if (!startText.trim() && !deltaText.trim()) return "{}";
   const candidates = [startText + deltaText, deltaText, startText].filter((c) => c && c.trim());
   for (const candidate of candidates) {
     try {
@@ -445,6 +447,8 @@ export interface GenerationParams {
   seed?: number;
 }
 
+/** Most stop sequences a Chat Completions request may carry (OpenRouter chat-completion api-ref `maxItems`, OpenAI the same). */
+const MAX_CHAT_STOP = 4;
 const finiteNumber = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v);
 
 /** Normalizes the public `stop` option (`string | string[]`) to a clean array, or undefined. */
@@ -460,11 +464,22 @@ export function normalizeStop(stop: string | string[] | undefined): string[] | u
  * `max_tokens`, `stop`, `seed`. Only set values are
  * emitted, so strict endpoints never see anything the caller did not ask for.
  */
-export function mapGenerationParamsToChat(params: GenerationParams | undefined): Record<string, unknown> {
+export function mapGenerationParamsToChat(params: GenerationParams | undefined, provider = "chat", modelRef = ""): Record<string, unknown> {
   const out: Record<string, unknown> = {};
   if (!params) return out;
   if (finiteNumber(params.maxOutputTokens) && params.maxOutputTokens > 0) out["max_tokens"] = Math.floor(params.maxOutputTokens);
-  if (params.stop && params.stop.length > 0) out["stop"] = params.stop;
+  if (params.stop && params.stop.length > 0) {
+    out["stop"] = params.stop.slice(0, MAX_CHAT_STOP);
+    if (params.stop.length > MAX_CHAT_STOP) {
+      emitProviderWarning({
+        provider,
+        capability: "stop sequences",
+        requested: `${params.stop.length} sequences (${modelRef})`,
+        reason: `Chat Completions allows at most ${MAX_CHAT_STOP} stop sequences.`,
+        fallback: `the first ${MAX_CHAT_STOP}`,
+      });
+    }
+  }
   if (finiteNumber(params.seed)) out["seed"] = Math.floor(params.seed);
   return out;
 }

package/src/scheduler/scheduled-actions.md

@@ -3,11 +3,11 @@ Schedules a sub-agent (a "scheduled action") to run LATER, once or on repeat, on
 Call get_datetime first whenever you create or reschedule, then pick DD from today's date.
 
 COMMANDS (one tool, the `command` field)
-- create: schedule a new action. Needs instructions, task and scheduled_action.{name, id, timeToDeliver, meridiem, startCookingInAdvance}. Optional: role, tools, timeoutMs, scheduled_action.repeatEvery, scheduled_action.retries.
+- create: schedule a new action. Needs instructions, task and scheduled_action.{name, id, timeToDeliver, meridiem, startCookingInAdvance}. Optional: role, tools, timeoutMs, scheduled_action.repeatEvery, scheduled_action.retries, scheduled_action.onMissed.
 - list: every action with its metadata and state (waiting, cooking, missed, done).
 - get: one action by `id`, with its latest run result.
 - update: change instructions, task, tools, timeoutMs, role or any scheduled_action field of the action `id`.
-- kill: delete the action `id` for good. If the answer says it is running, ask the user before retrying with force: true. purge: true also deletes its past run files.
+- delete: delete the action `id` for good. If the answer says it is running, ask the user before retrying with force: true. purge: true also deletes its past run files.
 - run_now: run the action `id` immediately, outside its schedule. Also fixes a missed run.
 - skip: ignore a missed run of `id` and wait for the next scheduled time.
 
@@ -18,7 +18,9 @@ SCHEDULED_ACTION FIELDS
 - meridiem: "AM" or "PM" for timeToDeliver.
 - startCookingInAdvance: "DD:HH:MM" as a duration (HH 00-23): how long before delivery the run starts. "00:00:10" = 10 minutes, "00:01:00" = 1 hour.
 - repeatEvery (optional): "DD:HH:MM" gap between deliveries. "01:00:00" = every day, "07:00:00" = every week. Omit to run once.
+- timeoutMs (optional, a top-level field of create and update, not inside scheduled_action): stop a run that takes longer than this many milliseconds. Omit it for no limit of your own; the host program may set a maximum that this cannot exceed.
 - retries (optional): extra attempts if a run fails, used only while there is still time before delivery. Default 0.
+- onMissed (optional): what to do when the host program was not running at delivery time. "skip" = move on to the next time. "run" = run it when the program is back. Omit it to be told (state missed) and decide with run_now or skip.
 
 EXAMPLES
 Daily brief, first delivery tomorrow at 7:00 AM, starting 30 minutes ahead:

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 });
 }