agent-accelerator 0.5.4 → 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/streaming/event-stream.ts

@@ -14,6 +14,8 @@ export interface EventStreamOptions {
   includePartial?: boolean;
   /** Max buffered events when no iterator is attached. Default 1000. Oldest dropped. */
   maxBufferedEvents?: number;
+  /** `false`: events go to listeners and waiting iterators only, never into the buffer (for a caller that only wants `result()`). Default true. */
+  buffer?: boolean;
   /** Max approx bytes for a single delta event. Default 1MB. Oversized dropped. */
   maxEventBytes?: number;
 }
@@ -61,6 +63,7 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
   private resolveFinalResult!: (result: AgentResponse) => void;
   private rejectFinalResult!: (err: Error) => void;
   private readonly includePartial: boolean;
+  private readonly buffered: boolean;
   private readonly maxBufferedEvents: number;
   private readonly maxEventBytes: number;
   /** First listener exception captured for inspection (Q-29/Q-41). */
@@ -80,6 +83,7 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
    */
   constructor(opts?: EventStreamOptions) {
     this.includePartial = opts?.includePartial !== false;
+    this.buffered = opts?.buffer !== false;
     this.maxBufferedEvents =
       typeof opts?.maxBufferedEvents === "number" && Number.isFinite(opts.maxBufferedEvents) && opts.maxBufferedEvents > 0
         ? Math.floor(opts.maxBufferedEvents)
@@ -151,8 +155,9 @@ export class AssistantMessageEventStream implements AsyncIterable<StreamEvent> {
     } else {
       // No waiter right now (typical between `next()` polls of a burst):
       // buffer for the iterator with a hard cap (Q-29). Overflow drops the
-      // oldest with an anomaly report — see `enqueueBounded`.
-      this.enqueueBounded(out);
+      // oldest with an anomaly report — see `enqueueBounded`. A stream built
+      // with `buffer: false` has no iterator to feed and keeps nothing.
+      if (this.buffered) this.enqueueBounded(out);
     }
   }
 

package/src/tools/executor.ts

@@ -422,6 +422,21 @@ function waitForRetry(ms: number, signal?: AbortSignal): Promise<void> {
   });
 }
 
+// Settles with `work`, or rejects "Tool execution aborted" the moment `signal` aborts, without waiting for a tool that never looks at its signal (it finishes in the background, its result is dropped); in: executeAttempt, out: the attempt's result or error.
+function raceAbort<T>(work: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+  if (!signal) return work;
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(new Error("Tool execution aborted"));
+    if (signal.aborted) {
+      work.catch(() => {}); // the abandoned tool may still fail later: nobody listens
+      onAbort();
+      return;
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+    work.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+  });
+}
+
 async function executeAttempt(
   toolDef: ToolDefinition,
   parsedInput: unknown,
@@ -429,7 +444,7 @@ async function executeAttempt(
   timeoutMs: number | undefined
 ): Promise<unknown> {
   if (!timeoutMs || timeoutMs <= 0) {
-    return toolDef.execute(parsedInput as any, context);
+    return raceAbort(Promise.resolve(toolDef.execute(parsedInput as any, context)), context.signal);
   }
 
   const controller = new AbortController();
@@ -453,7 +468,7 @@ async function executeAttempt(
       }, timeoutMs);
     });
     const result = await Promise.race([
-      Promise.resolve(toolDef.execute(parsedInput as any, executionContext)),
+      raceAbort(Promise.resolve(toolDef.execute(parsedInput as any, executionContext)), context.signal),
       timeout,
     ]);
     // A resolved promise can beat a timer callback even when the event loop

package/src/tools/tool.ts

@@ -61,22 +61,6 @@ export function resolveWhenBusy(
   return v === "steer" || v === "queue" ? v : "auto";
 }
 
-/**
- * Maps the Q-52 canonical worker-timeout knobs to the legacy `timeout` value
- * (`0` = no limit, `-1` = model sets per-task `timeoutMs`, `>0` = fixed ms).
- * An explicit `timeout`/`workerTimeoutMs` wins over `modelMaySetTimeout`.
- *
- * @example `normalizeWorkerTimeout({ modelMaySetTimeout: true }); // -1`
- */
-export function normalizeWorkerTimeout(
-  config?: { timeout?: number; workerTimeoutMs?: number; modelMaySetTimeout?: boolean }
-): number {
-  const explicit = config?.workerTimeoutMs ?? config?.timeout;
-  if (Number.isFinite(explicit as number)) return Math.floor(explicit as number);
-  if (config?.modelMaySetTimeout === true) return -1;
-  return 0;
-}
-
 /**
  * Normalizes the Q-52 `maxAttempts` alias to a `maxTries` value.
  * `maxTries` wins when both are set.

package/src/types/agent.ts

@@ -121,7 +121,8 @@ export interface AgentConfig {
    * - `{ mode: "steer" }`: only steer (inject into current turn) is allowed.
    * - `{ mode: "queue" }`: only queue (next-turn follow-up) is allowed.
    * - `{ mode: "auto" }` (default): caller picks per message via `enqueue` or `steer()`/`queue()`.
-   * `interrupt` (cancel stream now) is always available via `interrupt()`/`cancel()`/`AbortSignal`.
+   * `interrupt` (stop the active run now, optionally start a new message) is always available, whatever the mode:
+   * `interrupt()`, `interrupt(message)`, `enqueue: "interrupt"`, `cancel()` and `AbortSignal`.
    */
   midSession?: MidSessionConfig;
   /**
@@ -227,6 +228,25 @@ export interface AgentConfig {
   budget?: Budget;
   /** Run + network limits (Q-22). Turn/budget caps unlimited by default; network timeouts finite. */
   limits?: AgentRunLimits;
+  /**
+   * The only models this agent may use, as `provider/model` strings compared as written. Unset (default) = any model.
+   * Checked when the Agent is built (also for a config an agent edited through {@link Agent.fromConfig}); a model
+   * outside the list throws a `ConfigError`. Workers and `subagentModel` are not affected.
+   */
+  allowedModels?: string[];
+}
+
+/**
+ * The part of an agent that an agent may edit (self-improvement): see {@link Agent.toConfig} and {@link Agent.fromConfig}.
+ * Plain JSON. Every other setting (limits, budget, cache, thinking, keys, ...) stays with the developer.
+ */
+export interface EditableAgentConfig {
+  /** `provider/model`; must be in `allowedModels` when the developer set it. */
+  model?: string;
+  /** System instructions. */
+  instructions?: string;
+  /** Names of tools, picked from the developer's tool pool (`base.tools` of `fromConfig`). */
+  tools?: string[];
 }
 
 /** A run that a crash cut off (see {@link Agent.interrupted}). */
@@ -246,6 +266,7 @@ export interface AgentRunLimits {
   deadlineMs?: number;
   maxTotalTokens?: number;
   maxToolCallsPerRun?: number;
+  /** Network timeouts in ms. Defaults 300 000 / 120 000 / 300 000. `0` or `Infinity` turns one off. */
   requestTimeoutMs?: number;
   firstByteTimeoutMs?: number;
   streamIdleTimeoutMs?: number;
@@ -288,7 +309,7 @@ export interface DynamicSubagentsConfig {
   allowScheduledActions?: boolean;
   /** Developer-only worker model override. Never choosable by the Main Agent LLM. Falls back to top-level `subagentModel`, then `SUB_AGENT_MODEL` env, then the parent model. */
   model?: string | ModelSpec | ModelProviderInstance;
-  /** Max workers that may be open at once on this agent (the model must close one before spawning another). Defaults to 4. */
+  /** Max workers that may be open at once on this agent (the model must close one before spawning another). Default: no limit; set a whole number >= 1 to cap it. */
   maxSpawn?: number;
   /** Fixed reasoning level for all dynamic workers. The Main Agent cannot override it. Falls back to the parent level when omitted. */
   thinkingLevel?: ThinkingLevel;
@@ -300,27 +321,19 @@ export interface DynamicSubagentsConfig {
    */
   workerBudget?: Pick<Budget, "maxCostUsd" | "maxTotalTokens">;
   /**
-   * How many levels of workers may exist below this agent (default 3). `1` = workers cannot start workers of their own;
-   * `3` = a worker may start workers that start workers. A worker with levels left gets its own `subagents` tool, and
-   * its children can only be granted the tools the worker itself was granted. Whole number >= 1.
+   * How many levels of workers may exist below this agent. Default: no limit. `1` = workers cannot start workers of their
+   * own; `3` = a worker may start workers that start workers. A worker with levels left gets its own `subagents` tool, and
+   * its children can only be granted the tools the worker itself was granted. A whole number >= 1, or omit it for no limit.
    */
   maxDepth?: number;
   /** Tool pool available to dynamic workers. Workers receive zero tools unless the Main Agent grants a per-task `tools` subset by name. */
   tools?: Record<string, ToolDefinition> | ToolDefinition[];
-  /** Per-run timeout in ms of a SCHEDULED ACTION's worker (the `subagents` tool and `agent.workers` have no timeouts). `0` (default) = no limit. `-1` = the action sets its own `timeoutMs`. `>0` = fixed. */
-  timeout?: number;
   /**
-   * Canonical timeout in ms for scheduled-action workers (Q-52, preferred over `timeout`).
-   * Maps to `timeout`: `workerTimeoutMs ?? timeout ?? 0`. See
-   * `normalizeWorkerTimeout` (re-exported from the root entry).
+   * Longest a SCHEDULED ACTION's run may take, in ms (the `subagents` tool and `agent.workers` have no timeouts). An
+   * action can set its own shorter `timeoutMs`; this is the ceiling for it, and the limit for actions that set none.
+   * Default: no limit (`0` and `Infinity` mean the same).
    */
   workerTimeoutMs?: number;
-  /**
-   * Scheduled actions only: when true, each action sets its own `timeoutMs` (maps to
-   * `timeout: -1`). When both are set, an explicit `timeout`/`workerTimeoutMs`
-   * wins over `modelMaySetTimeout`.
-   */
-  modelMaySetTimeout?: boolean;
 }
 
 /** Per-run overrides for {@link Agent.run}, {@link Agent.ask}, and {@link Agent.stream}. */
@@ -346,8 +359,10 @@ export interface AgentRunOptions {
    * enforces `"steer"` or `"queue"`, that policy wins and this field is ignored.
    * When idle, this field is ignored and the call runs immediately.
    * Defaults to `"queue"` (finish current turn, run as next turn).
+   * `"interrupt"` is honored in every mode: it stops the active run (provider request, tools, workers) and starts this
+   * prompt as the next run, ahead of queued follow-ups.
    */
-  enqueue?: "steer" | "queue";
+  enqueue?: "steer" | "queue" | "interrupt";
   /** Headers merged for this run only. */
   headers?: Record<string, string>;
   /** Called for each text delta as it streams (only when stream:true). */