agent-accelerator 0.5.4 → 0.5.6

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/store.ts

@@ -1391,7 +1391,7 @@ function resolveEffectivePricing(
 /**
  * Prices one usage snapshot with integer micro-USD accumulation (Q-36).
  *
- * - Provider-reported `usage.cost.totalCost > 0` wins (source `provider`).
+ * - A provider-reported `usage.cost.totalCost` (a number, 0 included: free or cached) wins (source `provider`).
  * - Else catalog pricing via `resolveEffectivePricing` (source `catalog`).
  * - Else returns `undefined` (source `unknown` is implicit) — unknown stays
  *   unknown, never a fabricated 0 object.
@@ -1408,7 +1408,7 @@ export function priceUsage(
   opts?: { serviceTier?: ServiceTier | string; modelId?: string }
 ): PricedCost | undefined {
   const reported = usage?.cost;
-  if (reported && typeof reported.totalCost === "number" && reported.totalCost > 0) {
+  if (reported && typeof reported.totalCost === "number" && reported.totalCost >= 0) {
     const micro = (d?: number): number => (typeof d === "number" && d > 0 ? Math.round(d * 1_000_000) : 0);
     const inputMicroUSD = micro(reported.inputCost);
     const outputMicroUSD = micro(reported.outputCost);
@@ -1492,7 +1492,7 @@ export function addCostToUsage(
   spec?: ModelSpec,
   opts?: { serviceTier?: ServiceTier | string }
 ): TokenUsage["cost"] | undefined {
-  if (usage?.cost && typeof usage.cost.totalCost === "number" && usage.cost.totalCost > 0) {
+  if (usage?.cost && typeof usage.cost.totalCost === "number" && usage.cost.totalCost >= 0) {
     return usage.cost;
   }
   const priced = priceUsage(usage, spec, opts);

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). */

package/src/types/message.ts

@@ -9,7 +9,7 @@ export interface TextPart {
   thoughtSignature?: string;
 }
 
-/** Detail level a provider spends on one image or video (more detail = more input tokens). Google only; other providers ignore it with a warning. */
+/** Detail level a provider spends on one image or video (more detail = more input tokens). Google (images and videos) and OpenRouter (images, as `image_url.detail`) honour it; other providers ignore it with a warning. */
 export type MediaResolution = "low" | "medium" | "high" | "ultra_high";
 
 /** Image content accepted as a URL, data, path, or binary value. */

package/src/types/scheduler.ts

@@ -15,6 +15,12 @@ export interface ScheduleSpec {
   repeatEvery?: string;
   /** Extra attempts if a run fails, only while time remains before delivery. Default 0. */
   retries?: number;
+  /**
+   * What happens when the host program was not running at a delivery time. `"skip"`: move on to the next time (a one-shot
+   * is done). `"run"`: run it as soon as the program is back. Omitted: the action is marked `missed` and waits for
+   * `runScheduledAction` or `skipScheduledAction`.
+   */
+  onMissed?: "skip" | "run";
 }
 
 /** What `createScheduledAction` receives: dynamic sub-agent fields plus the schedule. */
@@ -24,6 +30,7 @@ export interface ScheduledActionInput {
   task: string;
   /** Names from the developer's `dynamicSubagents.tools` pool. */
   tools?: string[];
+  /** Longest one run may take, in ms. Never above `dynamicSubagents.workerTimeoutMs` when the developer set one. */
   timeoutMs?: number;
   scheduled_action: ScheduleSpec & {
     /** Human label. */
@@ -74,8 +81,8 @@ export interface ScheduledDelivery {
   late: boolean;
 }
 
-/** Result of `killScheduledAction`. */
-export type KillResult =
+/** Result of `deleteScheduledAction`. */
+export type DeleteResult =
   | { ok: true }
   | { ok: false; reason: "not_found" }
   | { ok: false; reason: "running"; message: string };

package/src/utils/errors.ts

@@ -113,7 +113,8 @@ const PART_TO_MODALITY: Record<string, "image" | "audio" | "video" | "pdf"> = {
 
 /**
  * Fails fast — before any network call — when the catalog knows the model
- * lacks a requested input modality (image/audio/video/document). Unknown
+ * lacks a requested input modality (image/audio/video/document; files are
+ * not checked on OpenRouter, which parses them for any model). Unknown
  * models (custom providers, dynamic routers) are skipped: the provider
  * verdict stands and surfaces via toConciseProviderError instead.
  */
@@ -130,6 +131,8 @@ export function assertModalitiesSupported(
       if (mapped) needed.add(mapped);
     }
   }
+  // OpenRouter reads a file with the model's native support or its own parser, so the catalog's "pdf" flag never gates a file there.
+  if (providerId === "openrouter") needed.delete("pdf");
   if (needed.size === 0) return;
   let supported: readonly string[] | undefined;
   try {

package/src/utils/headers.ts

@@ -23,7 +23,7 @@ export function getPackageVersion(): string {
     const v = (globalThis as any).process?.env?.npm_package_version;
     if (typeof v === "string" && v) return v;
   } catch {}
-  return "0.5.4";
+  return "0.5.6";
 }
 
 function getAgentAccelUserAgent(): string {

package/src/utils/media.ts

@@ -26,6 +26,11 @@ export function inferMimeType(input: string, fallback = "application/octet-strea
   if (clean.endsWith(".mp3")) return "audio/mp3";
   if (clean.endsWith(".wav")) return "audio/wav";
   if (clean.endsWith(".ogg")) return "audio/ogg";
+  if (clean.endsWith(".flac")) return "audio/flac";
+  if (clean.endsWith(".m4a")) return "audio/m4a";
+  if (clean.endsWith(".aac")) return "audio/aac";
+  if (clean.endsWith(".aiff") || clean.endsWith(".aif")) return "audio/aiff";
+  if (clean.endsWith(".mpeg") || clean.endsWith(".mpg")) return "video/mpeg";
   if (clean.endsWith(".mp4")) return "video/mp4";
   if (clean.endsWith(".webm")) return "video/webm";
   if (clean.endsWith(".mov")) return "video/quicktime";
@@ -53,8 +58,12 @@ export function sniffMimeType(bytes: Uint8Array): string | undefined {
   if (ascii(bytes, 0, "RIFF") && ascii(bytes, 8, "WAVE")) return "audio/wav";
   if (ascii(bytes, 0, "%PDF")) return "application/pdf";
   if (ascii(bytes, 0, "OggS")) return "audio/ogg";
+  if (ascii(bytes, 0, "fLaC")) return "audio/flac";
+  if (ascii(bytes, 0, "FORM") && ascii(bytes, 8, "AIF")) return "audio/aiff";
+  if (bytes[0] === 0xff && ((bytes[1] ?? 0) & 0xf6) === 0xf0) return "audio/aac"; // ADTS: sync bits plus layer 00 (MP3 frames have a non-zero layer)
   if (ascii(bytes, 0, "ID3") || (bytes[0] === 0xff && ((bytes[1] ?? 0) & 0xe0) === 0xe0)) return "audio/mp3";
-  if (ascii(bytes, 4, "ftyp")) return ascii(bytes, 8, "qt") ? "video/quicktime" : "video/mp4";
+  if (ascii(bytes, 4, "ftyp")) return ascii(bytes, 8, "M4A") || ascii(bytes, 8, "M4B") ? "audio/m4a" : ascii(bytes, 8, "qt") ? "video/quicktime" : "video/mp4";
+  if (bytes[0] === 0 && bytes[1] === 0 && bytes[2] === 1 && bytes[3] === 0xba) return "video/mpeg"; // MPEG program stream
   if (bytes[0] === 0x1a && bytes[1] === 0x45 && bytes[2] === 0xdf && bytes[3] === 0xa3) return "video/webm";
   return undefined;
 }