agent-accelerator 0.5.5 → 0.5.7

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

@@ -42,6 +42,7 @@ export type ProviderCapabilityStatus =
  */
 const emittedWarnings = new Set<string>();
 
+/** Warns once per provider, capability and request about something that cannot be applied as asked: a `provider_warning` bus event, the legacy global sink and console; in: the mappers and adapters, out: those channels. */
 export function emitProviderWarning(options: {
   provider: string;
   capability: string;
@@ -190,40 +191,6 @@ export function mapThinkingLevelToOpenRouterChat(
   return {};
 }
 
-/**
- * Maps a canonical ThinkingLevel onto OpenRouter Responses `reasoning.effort`.
- * Documented efforts: minimal|low|medium|high (server default medium).
- * Wire-validated extras: `none` disables reasoning output; `xhigh`/`max` are
- * echoed but are NOT documented levels, so they clamp to `high` with a warning.
- *
- * @deprecated The Responses skin is discontinued for OpenRouter
- * (removed from core). Use
- * {@link mapThinkingLevelToOpenRouterChat} with the stable Chat Completions
- * transport instead.
- */
-export function mapThinkingLevelToOpenRouter(
-  level: ThinkingLevel | string | undefined
-): { effort?: string } {
-  if (!level) return {};
-  const norm = String(level).toLowerCase().trim();
-  if (norm === "dynamic") return {}; // server default (medium)
-  if (norm === "none") return { effort: "none" };
-  if (norm === "xhigh" || norm === "max") {
-    emitProviderWarning({
-      provider: "openrouter",
-      capability: "thinking level",
-      requested: String(level),
-      reason: "OpenRouter documents reasoning efforts up to high.",
-      fallback: "reasoning effort high",
-    });
-    return { effort: "high" };
-  }
-  if (norm === "minimal" || norm === "low" || norm === "medium" || norm === "high") {
-    return { effort: norm };
-  }
-  return {};
-}
-
 /** Maps canonical ServiceTier onto OpenRouter `service_tier` (omit = auto). */
 export function mapServiceTierToOpenRouter(tier: ServiceTier | undefined): "flex" | "priority" | undefined {
   if (tier === "flex" || tier === "priority") return tier;
@@ -248,17 +215,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",
   });
 }
@@ -287,25 +254,6 @@ export function mapToolChoiceToOpenRouterChat(
   return undefined;
 }
 
-/** OpenRouter Responses `tool_choice` wire values.
- * @deprecated Discontinued skin; see {@link OpenRouterChatToolChoice}. */
-export type OpenRouterToolChoice = "auto" | "none" | "required" | { type: "function"; name: string };
-
-/**
- * Maps canonical toolChoice onto OpenRouter Responses `tool_choice`.
- * `auto` is the server default (omitted); `required` is natively supported
- * (validated); a function pin passes through verbatim.
- */
-export function mapToolChoiceToOpenRouter(
-  choice: "auto" | "none" | "required" | { type: "function"; function: { name: string } } | undefined
-): OpenRouterToolChoice | undefined {
-  if (!choice || choice === "auto") return undefined;
-  if (choice === "none" || choice === "required") return choice;
-  const name = choice.function?.name;
-  if (name) return { type: "function", name };
-  return undefined;
-}
-
 /**
  * Maps a canonical ThinkingLevel onto OpenAI Responses `reasoning.effort`.
  * Documented efforts: none|minimal|low|medium|high|xhigh|max (server default
@@ -383,6 +331,7 @@ export function normalizeToolChoice(
   return { mode: "any" };
 }
 
+// True for a non-array object; in: the argument and schema helpers, out: a type guard.
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -399,6 +348,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 +372,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 +396,9 @@ 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;
+// True for a finite number; in: the generation-param mappers, out: a type guard.
 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,15 +414,27 @@ 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;
 }
 
+// Warns that `stop`/`seed` have no parameter on this wire and are dropped; in: the OpenAI and Google mappers, out: provider_warning events.
 function warnUnsupportedStopSeed(provider: string, modelRef: string, params: GenerationParams, reasonSuffix: string): void {
   if (params.stop && params.stop.length > 0) {
     emitProviderWarning({
@@ -518,6 +484,7 @@ export function mapGenerationParamsToGoogle(
 // Structured outputs (canonical, pure, no I/O)
 // ---------------------------------------------------------------------------
 
+// True when a value looks like a Zod schema (parse/safeParse/_def/~standard); in: structured-output normalization, out: a boolean.
 function isZodLike(value: unknown): boolean {
   if (!value || typeof value !== "object") return false;
   const v = value as Record<string, unknown>;
@@ -529,6 +496,7 @@ function isZodLike(value: unknown): boolean {
   );
 }
 
+// True when a plain object has JSON Schema keywords; in: structured-output normalization, out: a boolean.
 function looksLikeJsonSchema(value: unknown): boolean {
   if (!isPlainObject(value)) return false;
   const v = value as Record<string, unknown>;
@@ -544,12 +512,14 @@ function looksLikeJsonSchema(value: unknown): boolean {
   );
 }
 
+// A structured-output name limited to letters, digits, `_` and `-` (64 chars), default `structured_output`; in: normalizeStructuredOutput, out: the name.
 function sanitizeOutputName(raw: unknown): string {
   const base = typeof raw === "string" && raw.trim() ? raw.trim() : "structured_output";
   const cleaned = base.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64) || "structured_output";
   return cleaned;
 }
 
+// A Zod schema or JSON Schema object as a JSON Schema object, else a ValidationError; in: normalizeStructuredOutput, out: the schema.
 function schemaToJsonSchema(schema: unknown, what: string): Record<string, unknown> {
   if (isZodLike(schema)) {
     try {
@@ -619,6 +589,7 @@ export function extractOutputValidator(output: unknown): { safeParse: (v: unknow
   return undefined;
 }
 
+// Removes a surrounding ```json fence from a model answer; in: parseStructuredOutput, out: the bare text.
 function stripCodeFences(text: string): string {
   const trimmed = text.trim();
   const fenced = trimmed.match(/^```(?:json)?\s*\n([\s\S]*?)\n```\s*$/i);

package/src/scheduler/architecture.md

@@ -0,0 +1,19 @@
+# src/scheduler/
+
+Scheduled actions: a worker that runs later (once or repeating) and saves its answer to a file. Off unless `dynamicSubagents.allowScheduledActions` is set.
+
+| File | What it is |
+| :-- | :-- |
+| `scheduler.ts` | One `Scheduler` per home folder: a 1 s unref'd clock that runs only while something is pending, startup sweep, cook/deliver state machine, and the public functions (`createScheduledAction`, `list/update/run/skip/deleteScheduledAction`). |
+| `store.ts` | Disk layer under `<home>/scheduled_actions/`: `tasks.json`, `deliveries.json`, run files; validation of records. |
+| `time.ts` | Pure `DD:HH:MM` and local-clock maths. No timezone, DST or `Intl`; `now` is always passed in. |
+| `tool.ts` + `scheduled-actions.md` | The model-facing `scheduled_actions` tool and `get_datetime`; the `.md` is the tool description. |
+
+## Invariants
+- The files are the truth: every write re-reads first and goes through the durable writer. The file format is a stable public contract: see `docs/scheduled-action-files.md` and add a changelog row for any change.
+- Write order when a run ends: run file, then `deliveries.json`, then `tasks.json`. The startup sweep repairs a crash in between.
+- `startCook` advances the next times BEFORE the run starts; a run still cooking when the next is due is skipped, never stacked.
+- Runs are fresh stateless workers built by `buildDynamicWorkerConfig`; their spending guardrail is `workerBudget` only.
+- The Agent registry holds `WeakRef`s by name: keep every Agent that owns actions referenced, or its runs become `missed`.
+- Times come from `Date`, local clock only. Tests inject `scheduler.now` / `tickMs` and call `tick()`.
+- Events: `scheduled_action.{created,updated,started,ready,failed,delivered,missed,skipped,deleted,invalid,store_corrupt,error}`.

package/src/scheduler/scheduler.ts

@@ -81,6 +81,7 @@ interface RunningEntry {
   missed: boolean;
 }
 
+// The message of any thrown value; in: catch blocks here, out: event and error text.
 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.
@@ -106,10 +107,12 @@ function usageFields(totals: UsageTotals | undefined): Partial<RunHeader> {
 // 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);
 
+// Emits one `scheduled_action.<code>` event on the telemetry bus; in: the scheduler and public functions, out: telemetryBus.
 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 });
 }
 
+// The ValidationError for an unknown action id; in: lookups by id, out: a thrown error.
 function notFound(id: string): ValidationError {
   return new ValidationError(`No scheduled action with id "${id}".`);
 }
@@ -118,6 +121,7 @@ function notFound(id: string): ValidationError {
 // Validation (collects EVERY problem so the model can fix a call in one go)
 // ---------------------------------------------------------------------------
 
+// Runs one validation step and records its message instead of throwing, so one call can report every problem; in: validateInput/checkSchedule, out: the problems list.
 function collect(problems: string[], fn: () => void): void {
   try {
     fn();
@@ -126,10 +130,12 @@ function collect(problems: string[], fn: () => void): void {
   }
 }
 
+// Throws unless the value is a non-empty string; in: field validation, out: collect.
 function requireText(field: string, value: unknown): void {
   if (typeof value !== "string" || !value.trim()) throw new ValidationError(`${field}: required, a non-empty string.`);
 }
 
+// Throws unless every requested worker tool name exists in the developer's pool; in: create/update validation, out: collect.
 function checkTools(value: unknown, pool: PoolTools): void {
   if (!Array.isArray(value) || value.some((n) => typeof n !== "string")) {
     throw new ValidationError("tools: must be an array of worker tool names, e.g. [\"recent_news\"].");
@@ -174,6 +180,7 @@ function checkSchedule(
   }
 }
 
+// Validates role, tools and timeoutMs of a create or update; in: validateInput/updateScheduledAction, out: the problems list.
 function checkOptionalFields(input: Pick<ScheduledActionPatch, "role" | "tools" | "timeoutMs">, pool: PoolTools | undefined, problems: string[]): void {
   if (input.role !== undefined && typeof input.role !== "string") problems.push("role: must be a string.");
   if (input.tools !== undefined && pool) collect(problems, () => checkTools(input.tools, pool));
@@ -208,9 +215,11 @@ export function validateInput(
   return problems;
 }
 
+// Joins validation problems into one numbered ValidationError message; in: create/update failures, out: the error text.
 const joinProblems = (what: string, problems: string[]): string =>
   `${what} (${problems.length} problem${problems.length === 1 ? "" : "s"}): ${problems.map((p, i) => `(${i + 1}) ${p}`).join(" ")}`;
 
+// Six random lowercase/digit characters appended to an action id; in: createScheduledAction, out: the unique id suffix.
 function randomSuffix(): string {
   const bytes = new Uint8Array(6);
   globalThis.crypto.getRandomValues(bytes);
@@ -244,6 +253,7 @@ export class Scheduler {
     (this.timer as { unref?: () => void }).unref?.();
   }
 
+  // Stops the clock's interval; in: tick when nothing is pending and resetSchedulers, out: no more ticks.
   stop(): void {
     if (this.timer) clearInterval(this.timer);
     this.timer = undefined;
@@ -266,6 +276,7 @@ export class Scheduler {
     }
   }
 
+  // Reports an invalid record or delivery once per file/id/problem and leaves the file untouched; in: snapshot/startCook, out: a scheduled_action.invalid warning.
   private warnInvalid(id: string, problem: string, file = "tasks.json"): void {
     const key = `${file}:${id}:${problem}`;
     if (this.warned.has(key)) return;
@@ -292,6 +303,7 @@ export class Scheduler {
     return { live, pending };
   }
 
+  // True while anything keeps the clock useful (a run in flight, a saved delivery, a waiting or cooking action); in: ensureRunning and tick, out: start/stop of the interval.
   private hasPending(): boolean {
     const { live, pending } = this.snapshot();
     return this.running.size > 0 || pending.length > 0 || live.some((t) => t.state === "waiting" || t.state === "cooking");
@@ -359,6 +371,7 @@ export class Scheduler {
 
   // ----- delivery ----------------------------------------------------------
 
+  // Delivers every saved run whose delivery time has come; in: tick, out: deliver calls.
   private deliverDue(now: Date): void {
     for (const entry of this.snapshot().pending) {
       if (parseLocalIso(entry.deliverAt).getTime() <= now.getTime()) this.deliver(entry, now);
@@ -394,6 +407,7 @@ export class Scheduler {
 
   // ----- starting runs -----------------------------------------------------
 
+  // Starts waiting actions whose cook time has come and skips the overlap of those still cooking; in: tick, out: startCook/skipOverlap calls.
   private startDue(now: Date): void {
     for (const t of this.snapshot().live) {
       if (!t.nextCookAt || parseLocalIso(t.nextCookAt).getTime() > now.getTime()) continue;
@@ -468,6 +482,7 @@ export class Scheduler {
     return started;
   }
 
+  // The display name of an action from tasks.json, else its id; in: startCook's no-agent message, out: event text.
   private nameOf(id: string): string {
     return readTasks(this.home).find((t) => t.id === id)?.name ?? id;
   }
@@ -511,6 +526,7 @@ export class Scheduler {
 
   // ----- the run -----------------------------------------------------------
 
+  // Runs one action to its outcome and writes the result unless the action was deleted meanwhile; in: launch, out: finish.
   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);
@@ -556,6 +572,7 @@ export class Scheduler {
     }
   }
 
+  // One worker run with a per-attempt timeout and the delete signal, raced so a hung provider cannot hold it; in: execute, out: the worker's AgentResponse.
   private async attempt(worker: Agent, task: ScheduledActionRecord, agent: Agent, entry: RunningEntry): Promise<AgentResponse> {
     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.
@@ -613,6 +630,7 @@ export class Scheduler {
 
   // ----- commands ----------------------------------------------------------
 
+  // Starts an action immediately outside its schedule (also resolves a missed one); in: runScheduledAction, out: the cooking record.
   runNow(id: string): ScheduledActionRecord {
     const rec = readTasks(this.home).find((t) => t.id === id);
     if (!rec) throw notFound(id);
@@ -629,6 +647,7 @@ export class Scheduler {
     return started;
   }
 
+  // Ignores a missed occurrence and schedules the next one (a one-shot becomes done); in: skipScheduledAction and onMissed: skip, out: the updated record.
   skip(id: string): ScheduledActionRecord {
     const now = this.now();
     const rec = updateTasks(this.home, (tasks) => {
@@ -647,6 +666,7 @@ export class Scheduler {
     return rec;
   }
 
+  // Deletes an action (aborting a cooking run only with force) and optionally purges its run files; in: deleteScheduledAction, out: a DeleteResult.
   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" };
@@ -699,6 +719,7 @@ export function resetSchedulers(): void {
   schedulers.clear();
 }
 
+// The scheduler of a resolved home (option, setHome, env or default); in: the public functions, out: a Scheduler.
 const schedulerFor = (opts?: HomeOptions): Scheduler => getScheduler(resolveHome(opts?.home));
 
 /** Makes `agent` the live runner for actions created under its name, and starts the clock if work is pending. */

package/src/scheduler/store.ts

@@ -72,8 +72,11 @@ export interface RunHeader {
   error?: string;
 }
 
+// The `scheduled_actions` folder of a home; in: the path helpers, out: its path.
 const baseDir = (home: string): string => path.join(home, "scheduled_actions");
+// Path of tasks.json; in: readTasks/updateTasks, out: its path.
 const tasksFile = (home: string): string => path.join(baseDir(home), "tasks.json");
+// Path of deliveries.json; in: readDeliveries/updateDeliveries, out: its path.
 const deliveriesFile = (home: string): string => path.join(baseDir(home), "deliveries.json");
 
 /** Absolute path of a run file given its `scheduled_actions/`-relative path. */
@@ -134,6 +137,7 @@ function readList(file: string, key: "tasks" | "pending"): Raw[] {
   return list ?? [];
 }
 
+// Writes `{ version, <key>: [...] }` durably (with a .bak); in: updateTasks/updateDeliveries, out: the file.
 function writeList(file: string, key: "tasks" | "pending", list: Raw[]): void {
   writeFileDurable(file, JSON.stringify({ version: 1, [key]: list }, null, 2) + "\n");
 }
@@ -151,6 +155,7 @@ export function updateTasks<T>(home: string, fn: (tasks: ScheduledActionRecord[]
   return result;
 }
 
+/** Every saved delivery as stored (entries may be invalid: check with validateDelivery); in: the scheduler, out: PendingDelivery[]. */
 export function readDeliveries(home: string): PendingDelivery[] {
   return readList(deliveriesFile(home), "pending") as unknown as PendingDelivery[];
 }
@@ -229,6 +234,7 @@ export function validateDelivery(raw: unknown): string | undefined {
 // Run files
 // ---------------------------------------------------------------------------
 
+// Renders a run file: the `---` header lines, a blank line, the result text; in: writeRunFile, out: the file text.
 function renderRun(header: RunHeader, body: string): string {
   const lines = ["---"];
   for (const [key, value] of Object.entries(header)) {

package/src/scheduler/time.ts

@@ -15,7 +15,9 @@ const DAYS = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday",
 const DDHHMM = /^(\d{2,}):(\d{2}):(\d{2})$/;
 const LOCAL_ISO = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})$/;
 
+// Two-digit zero padding; in: date formatting here, out: a string.
 const pad2 = (n: number): string => String(n).padStart(2, "0");
+// JSON text of a value for error messages; in: the validators, out: a string.
 const show = (v: unknown): string => JSON.stringify(v) ?? String(v);
 
 /** Parses `DD:HH:MM` (DD >= 2 digits, MM < 60). HH is range-checked by the caller. */

package/src/session/architecture.md

@@ -0,0 +1,19 @@
+# src/session/
+
+Saving a conversation, its spending and its tool logs.
+
+| File | What it is |
+| :-- | :-- |
+| `store.ts` | Snapshot format (`session.json`, one line per field and per turn), load validation, `SessionTelemetry`, media extraction, journal replay (`replayJournal`), and `priceUsage` (the one cost model, integer micro-USD). |
+| `journal.ts` | `SessionJournal`: after each step appends one fsynced line to `journal.ndjson`; writes a fresh snapshot (new `epoch`) when history changed any other way or the journal passed 500 lines / 4 MB. |
+| `usage.ts` | Pure spending accounting: `UsageTotals`, `usageLine`, `buildUsageReport`. No Agent import. |
+| `tool-log.ts` | `ToolLogs`: one fsynced NDJSON file per tool call under `<session>/tool-logs/`. |
+
+## Invariants
+- Layout: `<home>/sessions/<id>/{session.json, journal.ndjson, media/, tool-logs/, workers/}`.
+- A journal whose header epoch differs from the snapshot's is ignored on load.
+- Journal record types: `base`, `msg`, `meta`, `run`, `end`, `tool`, `pending`, `usage`. Replay ignores unknown types, drops a torn last line, and stops at earlier damage with `session.journal_corrupt`.
+- Media is content-addressed (`media/<kind>-h<hash>.<ext>`), written once, never deleted.
+- Valid sessions over the load limits throw `SessionLoadError` and are never quarantined; only corrupt files are renamed `*.corrupt-<ts>`.
+- Pricing: a provider-reported cost wins and is never rescaled; unknown pricing stays unknown, never $0; cache reads and writes are subsets of input.
+- Never call `saveSessionDir` on a folder an Agent persists to.