agent-accelerator 0.5.6 → 0.5.7

package/src/providers/openai.ts

@@ -167,6 +167,7 @@ const DEFAULT_BASE_URL = "https://api.openai.com/v1";
 // Request building (canonical -> Responses)
 // ---------------------------------------------------------------------------
 
+// Endpoint from the option, OPENAI_BASE_URL/OPENAI_API_BASE, else api.openai.com; in: each request, out: the base URL without a trailing slash.
 function resolveBaseUrl(options?: ProviderRequestOptions): string {
   return (
     options?.baseUrl ||
@@ -178,6 +179,7 @@ function resolveBaseUrl(options?: ProviderRequestOptions): string {
   ).replace(/\/+$/, "");
 }
 
+// Key from the option or env, or `unused` when custom headers carry the auth; in: each request, out: the key or undefined.
 function resolveApiKey(options?: ProviderRequestOptions): string | undefined {
   const key = getApiKey("openai", options?.apiKey, options?.env);
   if (key) return key;
@@ -191,6 +193,7 @@ function cleanModelId(model: string | ModelSpec): string {
   return rawId.replace(/^openai\//i, "");
 }
 
+// Canonical tool declarations as Responses function tools; in: options.tools, out: request `tools`.
 function toOpenAITools(tools?: StandardToolDeclaration[]): Array<Record<string, unknown>> | undefined {
   if (!tools || tools.length === 0) return undefined;
   return tools.map((t) => ({
@@ -202,6 +205,7 @@ function toOpenAITools(tools?: StandardToolDeclaration[]): Array<Record<string,
   }));
 }
 
+// Text and media parts as input_text, input_image and input_file blocks; web links pass through, the rest is inlined as data URLs; in: a user message's parts, out: fullHistoryInput.
 async function contentPartsToBlocks(parts: ContentPart[]): Promise<ResponseContentPart[]> {
   const blocks: ResponseContentPart[] = [];
   for (const part of parts) {
@@ -258,17 +262,20 @@ async function contentPartsToBlocks(parts: ContentPart[]): Promise<ResponseConte
   return blocks;
 }
 
+// A tool result as the text of a function_call_output item; in: fullHistoryInput, out: a string.
 function resultToOutput(result: unknown): string {
   if (typeof result === "string") return result;
   return safeStringify(result);
 }
 
+// Makes an id safe for the Responses wire (allowed characters, at most 64, no trailing underscores); in: fullHistoryInput, out: the id.
 function normalizeResponsesIdPart(part: string): string {
   const sanitized = String(part ?? "").replace(/[^a-zA-Z0-9_-]/g, "_");
   const truncated = sanitized.length > 64 ? sanitized.slice(0, 64) : sanitized;
   return truncated.replace(/_+$/, "") || "fc_unknown";
 }
 
+// Gives a function-call item id the required `fc_` prefix; in: fullHistoryInput, out: the id.
 function normalizeResponsesItemId(itemId: string): string {
   let norm = normalizeResponsesIdPart(itemId);
   if (!norm.startsWith("fc_")) {
@@ -390,6 +397,7 @@ async function fullHistoryInput(context: ProviderContext): Promise<ResponseInput
 // Response mapping (Responses -> canonical)
 // ---------------------------------------------------------------------------
 
+// Responses usage as TokenUsage, clamping cache reads to input; in: a response or the completed event, out: TokenUsage.
 function mapUsage(raw?: ResponsesObject["usage"]): TokenUsage {
   const input = raw?.input_tokens ?? 0;
   const output = raw?.output_tokens ?? 0;
@@ -406,6 +414,7 @@ function mapUsage(raw?: ResponsesObject["usage"]): TokenUsage {
   };
 }
 
+// Turns a Responses object into text, reasoning, tool calls and usage, mapping refusals and incomplete to finish reasons and throwing on failed; in: generate, out: ProviderGenerateResult.
 function parseResponse(
   response: ResponsesObject,
   modelId: string,
@@ -509,6 +518,7 @@ export class OpenAIResponsesProvider implements Provider {
     return getModelsForProvider("openai");
   }
 
+  // The catalog spec of a model, else a permissive generic one; in: the registry, out: a ModelSpec.
   getModel(modelId: string): ModelSpec | undefined {
     const clean = cleanModelId(modelId);
     return (
@@ -519,6 +529,7 @@ export class OpenAIResponsesProvider implements Provider {
     );
   }
 
+  // Builds the stateless Responses request (full history, store:false, tools, reasoning, tier, text.format, cache key and retention); in: generate/stream, out: the body.
   private async buildBody(
     modelId: string,
     context: ProviderContext,
@@ -620,6 +631,7 @@ export class OpenAIResponsesProvider implements Provider {
     return body;
   }
 
+  // Fetch options with session-affinity headers, JSON content type and the Bearer key; in: doFetch and stream, out: RequestInit.
   private requestInit(
     body: ResponsesRequestBody,
     options: ProviderRequestOptions | undefined,
@@ -640,6 +652,7 @@ export class OpenAIResponsesProvider implements Provider {
     return { method: "POST", headers, body: JSON.stringify(body), signal };
   }
 
+  // One HTTP call under the request timeout, returning status, headers and body text; in: generate, out: the raw reply.
   private async doFetch(
     url: string,
     body: ResponsesRequestBody,
@@ -662,6 +675,7 @@ export class OpenAIResponsesProvider implements Provider {
     }
   }
 
+  // Throws a concise provider error (status, code, Retry-After, key hint) for a non-2xx reply; in: generate and stream, out: nothing or a thrown error.
   private throwIfError(
     status: number,
     url: string,
@@ -692,6 +706,7 @@ export class OpenAIResponsesProvider implements Provider {
     throw toConciseProviderError(err, "openai", modelId);
   }
 
+  // Non-streaming turn as one retried JSON request; in: runAgentLoop, out: ProviderGenerateResult.
   async generate(
     model: string | ModelSpec,
     context: ProviderContext,
@@ -773,6 +788,7 @@ export class OpenAIResponsesProvider implements Provider {
     }
   }
 
+  // Streaming turn over SSE: assembles text, reasoning, tool calls and usage, retrying only before the first byte; in: streamAgentLoop, out: an AssistantMessageEventStream.
   stream(
     model: string | ModelSpec,
     context: ProviderContext,
@@ -793,7 +809,7 @@ export class OpenAIResponsesProvider implements Provider {
           );
         }
         assertModalitiesSupported(context, "openai", clean);
-    assertNoVideoPartsOnResponses(context, "openai", clean);
+        assertNoVideoPartsOnResponses(context, "openai", clean);
         const baseUrl = resolveBaseUrl(options);
         const url = `${baseUrl}/responses`;
         const sessionId = options?.sessionId;

package/src/providers/openrouter.ts

@@ -145,6 +145,7 @@ const DEFAULT_BASE_URL = "https://openrouter.ai/api/v1";
 // Request building (canonical -> Chat Completions)
 // ---------------------------------------------------------------------------
 
+// Endpoint from the option, OPENROUTER_BASE_URL, else openrouter.ai; in: each request, out: the base URL without a trailing slash.
 function resolveBaseUrl(options?: ProviderRequestOptions): string {
   return (
     options?.baseUrl ||
@@ -154,6 +155,7 @@ function resolveBaseUrl(options?: ProviderRequestOptions): string {
   ).replace(/\/+$/, "");
 }
 
+// Key from the option or env, or `unused` when custom headers carry the auth; in: each request, out: the key or undefined.
 function resolveApiKey(options?: ProviderRequestOptions): string | undefined {
   const key = getApiKey("openrouter", options?.apiKey, options?.env);
   if (key) return key;
@@ -172,11 +174,13 @@ function cleanModelId(model: string | ModelSpec): string {
 
 // The HTTP status of an error chunk inside a stream (the HTTP status itself is 200): its numeric `code`, else the status of its retryable `error_type` (errors-and-debugging.md, "Typed Error Codes"); in: the chunk's error, out: streamInto, where it makes the error retryable.
 const RETRYABLE_ERROR_TYPE_STATUS: Record<string, number> = { rate_limit_exceeded: 429, provider_overloaded: 503, provider_unavailable: 502, timeout: 504, server: 500 };
+// HTTP-like status of an error chunk inside a stream, or undefined when unknown; in: streamInto's error branch, out: the status that makes the error retryable.
 function midStreamStatus(code: unknown, errorType: unknown): number | undefined {
   if (typeof code === "number" && Number.isInteger(code) && code >= 100 && code <= 599) return code;
   return typeof errorType === "string" ? RETRYABLE_ERROR_TYPE_STATUS[errorType] : undefined;
 }
 
+// Canonical tool declarations as Chat Completions function tools; in: options.tools, out: request `tools`.
 function toOpenRouterTools(tools?: StandardToolDeclaration[]): Array<Record<string, unknown>> | undefined {
   if (!tools || tools.length === 0) return undefined;
   return tools.map((t) => ({
@@ -192,6 +196,7 @@ function toOpenRouterTools(tools?: StandardToolDeclaration[]): Array<Record<stri
 
 // The `input_audio.format` for a MIME type: Chat Completions takes any format string the provider supports (audio.md: wav, mp3, aiff, aac, ogg, flac, m4a, pcm16 ...), so the real format is sent, never a guess; in: an audio part's MIME type, out: contentPartsToBlocks.
 const AUDIO_FORMAT: Record<string, string> = { wav: "wav", wave: "wav", mpeg: "mp3", mp3: "mp3", mp4: "m4a", m4a: "m4a", aac: "aac", ogg: "ogg", flac: "flac", aiff: "aiff" };
+// The `input_audio.format` for an audio MIME type (see AUDIO_FORMAT above); in: contentPartsToBlocks, out: the format string.
 function audioFormatFor(mimeType?: string): string {
   const subtype = (mimeType || "").toLowerCase().split(";")[0]!.split("/")[1]?.replace(/^x-/, "") ?? "";
   return AUDIO_FORMAT[subtype] ?? (subtype || "mp3");
@@ -278,6 +283,7 @@ async function contentPartsToBlocks(parts: ContentPart[]): Promise<ChatContentPa
   return blocks;
 }
 
+// A tool result as the text of a tool message; in: fullHistoryMessages, out: a string.
 function resultToOutput(result: unknown): string {
   if (typeof result === "string") return result;
   return safeStringify(result);
@@ -392,6 +398,7 @@ async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessag
 // Response mapping (Chat Completions -> canonical)
 // ---------------------------------------------------------------------------
 
+// Chat usage as TokenUsage with cache reads clamped to input, cache writes, reasoning tokens and OpenRouter's reported cost (0 counts); in: the last stream chunk, out: TokenUsage.
 function mapUsage(raw?: ChatUsage): TokenUsage {
   const input = raw?.prompt_tokens ?? 0;
   const output = raw?.completion_tokens ?? 0;
@@ -430,6 +437,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     return getModelsForProvider("openrouter");
   }
 
+  // The catalog spec of a model, else a permissive generic one; in: the registry, out: a ModelSpec.
   getModel(modelId: string): ModelSpec | undefined {
     const clean = cleanModelId(modelId);
     return (
@@ -440,6 +448,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     );
   }
 
+  // Builds the Chat request (messages, tools, tool_choice, reasoning, tier, cache_control, generation controls, response_format, session_id); in: streamInto, out: the body.
   private async buildBody(
     modelId: string,
     context: ProviderContext,
@@ -518,6 +527,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     return body;
   }
 
+  // Fetch options with session and opt-in attribution headers, JSON content type and the Bearer key; in: streamInto, out: RequestInit.
   private requestInit(
     body: ChatRequestBody,
     options: ProviderRequestOptions | undefined,
@@ -537,6 +547,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     return { method: "POST", headers, body: JSON.stringify(body), signal };
   }
 
+  // Throws a concise provider error (status, code, Retry-After, key and media-link hints) for a non-2xx reply, marking the in-flight-budget 402 retryable; in: streamInto, out: nothing or a thrown error.
   private throwIfError(
     status: number,
     url: string,
@@ -612,6 +623,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     }
   }
 
+  // Streaming turn: a normal event stream from streamInto; in: streamAgentLoop, out: an AssistantMessageEventStream.
   stream(
     model: string | ModelSpec,
     context: ProviderContext,

package/src/providers/registry.ts

@@ -42,6 +42,7 @@ const FIRST_CLASS = new Set([
 // resolve anywhere.
 const REMOVED_PROVIDERS = new Set(["opencode", "opencode-go"]);
 
+// The error text for a removed provider prefix; in: assertProviderNotRemoved, out: a message.
 function removedProviderMessage(id: string): string {
   return (
     `[Agent Accelerator] Provider "${id}" has been removed: OpenCode free models are ` +

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;
@@ -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);
 }
@@ -449,6 +398,7 @@ export interface GenerationParams {
 
 /** 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. */
@@ -484,6 +434,7 @@ export function mapGenerationParamsToChat(params: GenerationParams | undefined,
   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({
@@ -533,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>;
@@ -544,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>;
@@ -559,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 {
@@ -634,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.