agent-accelerator 0.5.9 → 0.6.0

package/src/providers/shared.ts

@@ -28,9 +28,7 @@ export function parseArguments(raw: string | undefined): Record<string, unknown>
 
 /** Trims/collapses assembled thinking parts (no edge-tripling). */
 export function normalizeThinkingParts(parts: string[]): string | undefined {
-  const cleaned = parts
-    .map((p) => p.replace(/\n{3,}/g, "\n\n").trim())
-    .filter((p) => p.length > 0);
+  const cleaned = parts.map((p) => p.replace(/\n{3,}/g, "\n\n").trim()).filter((p) => p.length > 0);
   return cleaned.length > 0 ? cleaned.join("\n") : undefined;
 }
 
@@ -49,21 +47,35 @@ export function redactedHeaders(headers: Record<string, string>): Record<string,
  * 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; limitSource?: string } {
+export function readErrorPayload(bodyText: 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; limit_source?: 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 =
-        err.type ?? err.metadata?.error_type ?? (first as { error_type?: string })?.error_type;
+      const errorType = err.type ?? err.metadata?.error_type ?? (first as { error_type?: string })?.error_type;
       const rawCandidate =
         (err as { metadata?: { raw?: unknown } }).metadata?.raw ??
         (first as { metadata?: { raw?: unknown } })?.metadata?.raw;
-      const raw = typeof rawCandidate === "string" && rawCandidate.trim() ? rawCandidate.trim().slice(0, 500) : undefined;
+      const raw =
+        typeof rawCandidate === "string" && rawCandidate.trim() ? rawCandidate.trim().slice(0, 500) : undefined;
       return {
         message: err.message,
         ...(code !== undefined ? { code } : {}),
@@ -111,7 +123,9 @@ export function isNotFoundChainError(error: unknown): boolean {
   );
   if (status === 404) return true;
   // `providerCode` on a wrapped ProviderError (its `code` is the SDK kind), `code` on a raw error.
-  return [err["providerCode"], err["code"], err["errorType"]].some((c) => String(c ?? "").toLowerCase() === "not_found");
+  return [err["providerCode"], err["code"], err["errorType"]].some(
+    (c) => String(c ?? "").toLowerCase() === "not_found"
+  );
 }
 
 /** Per-request timeout ms from provider options. */
@@ -121,25 +135,40 @@ export function timeoutFor(options: { timeoutMs?: number } | undefined): number
 }
 
 /** Merges a parent signal with a timeout into one effective signal. Caller must call cleanup when the request settles so the timer never holds the loop open. */
-export function combinedSignal(signal?: AbortSignal, timeoutMs?: number): { signal: AbortSignal | undefined; cleanup: () => void } {
+export function combinedSignal(
+  signal?: AbortSignal,
+  timeoutMs?: number
+): { signal: AbortSignal | undefined; cleanup: () => void } {
   if (timeoutMs === undefined) return { signal, cleanup: () => {} };
   const ctrl = new AbortController();
   const timer = setTimeout(() => {
-    try { ctrl.abort(); } catch {}
+    try {
+      ctrl.abort();
+    } catch {}
   }, timeoutMs);
-  try { (timer as unknown as { unref?: () => void }).unref?.(); } catch {}
+  try {
+    (timer as unknown as { unref?: () => void }).unref?.();
+  } catch {}
   const cleanup = () => {
-    try { clearTimeout(timer); } catch {}
+    try {
+      clearTimeout(timer);
+    } catch {}
   };
   if (signal) {
     if (signal.aborted) {
       cleanup();
       ctrl.abort(signal.reason); // the caller's reason survives (`interrupt(new Error("..."))`)
     } else {
-      signal.addEventListener("abort", () => {
-        cleanup();
-        try { ctrl.abort(signal.reason); } catch {}
-      }, { once: true });
+      signal.addEventListener(
+        "abort",
+        () => {
+          cleanup();
+          try {
+            ctrl.abort(signal.reason);
+          } catch {}
+        },
+        { once: true }
+      );
     }
   }
   return { signal: ctrl.signal, cleanup };
@@ -167,7 +196,11 @@ export function hasAuthHeader(headers: Record<string, string> | undefined): bool
   if (!headers) return false;
   for (const [k, v] of Object.entries(headers)) {
     const lower = k.toLowerCase();
-    if ((lower === "authorization" || lower === "cf-aig-authorization") && typeof v === "string" && v.trim().length > 0) {
+    if (
+      (lower === "authorization" || lower === "cf-aig-authorization") &&
+      typeof v === "string" &&
+      v.trim().length > 0
+    ) {
       return true;
     }
   }
@@ -180,7 +213,10 @@ export function hasTruncatedToolArguments(args: unknown): boolean {
 }
 
 // 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 {
+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));
 }
@@ -220,7 +256,9 @@ export function clampToolCallId(id: string): string {
 
 // 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";
+  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.
@@ -249,7 +287,8 @@ export function parseRetryAfterMs(headers: Record<string, string> | undefined, n
     return undefined;
   };
   const ms = get("retry-after-ms");
-  if (ms !== undefined && ms.trim() !== "" && Number.isFinite(Number(ms)) && Number(ms) >= 0) return Math.round(Number(ms));
+  if (ms !== undefined && ms.trim() !== "" && Number.isFinite(Number(ms)) && Number(ms) >= 0)
+    return Math.round(Number(ms));
   const ra = get("retry-after");
   if (ra === undefined || ra.trim() === "") return undefined;
   const secs = Number(ra);
@@ -287,12 +326,16 @@ export function openStreamResponse(args: {
 }
 
 /** Retry knobs from provider request options, in the shape `withRetries` expects. */
-export function retryOptionsFrom(options: {
-  maxRetries?: number;
-  maxRetryDelayMs?: number;
-  retryBaseDelayMs?: number;
-  retryBudgetMs?: number;
-} | undefined): { maxRetries?: number; maxRetryDelayMs?: number; baseDelayMs?: number; retryBudgetMs?: number } {
+export function retryOptionsFrom(
+  options:
+    | {
+        maxRetries?: number;
+        maxRetryDelayMs?: number;
+        retryBaseDelayMs?: number;
+        retryBudgetMs?: number;
+      }
+    | undefined
+): { maxRetries?: number; maxRetryDelayMs?: number; baseDelayMs?: number; retryBudgetMs?: number } {
   return {
     maxRetries: options?.maxRetries,
     maxRetryDelayMs: options?.maxRetryDelayMs,
@@ -306,7 +349,10 @@ export function retryOptionsFrom(options: {
 // ---------------------------------------------------------------------------
 
 // 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 } {
+export function linkStreamAbort(
+  eventStream: AssistantMessageEventStream,
+  signal: AbortSignal | undefined
+): { linked: AbortController; release: () => void } {
   const linked = new AbortController();
   const forwardUserAbort = (): void => {
     try {
@@ -338,7 +384,11 @@ export function linkStreamAbort(eventStream: AssistantMessageEventStream, signal
 }
 
 // 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> {
+export async function withAbortTimer<T>(
+  controller: AbortController,
+  ms: number | undefined,
+  run: () => Promise<T>
+): Promise<T> {
   const timer =
     ms && ms > 0
       ? setTimeout(() => {
@@ -397,13 +447,17 @@ export function incompleteStreamCheck(a: {
 }): 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;
+  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";
+  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

@@ -18,12 +18,7 @@ import { TRUNCATED_ARGS_KEY } from "./types/tool.ts";
 import { telemetryBus } from "./telemetry.ts";
 
 /** Classification of a canonical capability on a given provider. */
-export type ProviderCapabilityStatus =
-  | "NATIVE"
-  | "TRANSLATED"
-  | "AUTOMATIC"
-  | "EMULATED"
-  | "UNSUPPORTED";
+export type ProviderCapabilityStatus = "NATIVE" | "TRANSLATED" | "AUTOMATIC" | "EMULATED" | "UNSUPPORTED";
 
 /**
  * Single warning mechanism for provider capability differences.
@@ -65,8 +60,12 @@ export function emitProviderWarning(options: {
     reason: options.reason,
     fallback: options.fallback,
   });
-  try { (globalThis as any).__agentAccelWarnSink?.(msg, options); } catch {}
-  try { console.warn(msg); } catch {}
+  try {
+    (globalThis as any).__agentAccelWarnSink?.(msg, options);
+  } catch {}
+  try {
+    console.warn(msg);
+  } catch {}
 }
 
 /** Clears deduped-warning state (mainly for tests). */
@@ -124,9 +123,7 @@ export function clearSessionRouting(sessionId?: string): void {
  * Maps a canonical ThinkingLevel onto Google Interactions `thinking_level`.
  * Google values: minimal|low|medium|high (no off switch, no xhigh/max).
  */
-export function mapThinkingLevelToGoogle(
-  level: ThinkingLevel | string | undefined
-): { thinkingLevel?: string } {
+export function mapThinkingLevelToGoogle(level: ThinkingLevel | string | undefined): { thinkingLevel?: string } {
   if (!level) return {};
   const norm = String(level).toLowerCase().trim();
   if (norm === "dynamic") return {}; // server dynamic default (NATIVE)
@@ -171,9 +168,7 @@ export function mapServiceTierToGoogle(tier: ServiceTier | undefined): "flex" |
  * the discontinued Responses skin, which clamped `xhigh` — everything passes
  * through. `max` rides the same verbatim path. `dynamic` omits (server default).
  */
-export function mapThinkingLevelToOpenRouterChat(
-  level: ThinkingLevel | string | undefined
-): { effort?: string } {
+export function mapThinkingLevelToOpenRouterChat(level: ThinkingLevel | string | undefined): { effort?: string } {
   if (!level) return {};
   const norm = String(level).toLowerCase().trim();
   if (norm === "dynamic") return {}; // server default
@@ -216,9 +211,16 @@ export function resolveCache(
 }
 
 /** 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 {
+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") && kinds.includes(p.type) && 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({
@@ -231,11 +233,7 @@ export function warnIgnoredMediaResolution(provider: string, messages: Message[]
 }
 
 /** OpenRouter Chat Completions `tool_choice` wire values. */
-export type OpenRouterChatToolChoice =
-  | "auto"
-  | "none"
-  | "required"
-  | { type: "function"; function: { name: string } };
+export type OpenRouterChatToolChoice = "auto" | "none" | "required" | { type: "function"; function: { name: string } };
 
 /**
  * Maps canonical toolChoice onto Chat Completions `tool_choice`.
@@ -260,9 +258,7 @@ export function mapToolChoiceToOpenRouterChat(
  * medium). Unlike OpenRouter (which clamps xhigh), OpenAI documents xhigh
  * and max natively so they pass through verbatim. `dynamic` omits (server default).
  */
-export function mapThinkingLevelToOpenAI(
-  level: ThinkingLevel | string | undefined
-): { effort?: string } {
+export function mapThinkingLevelToOpenAI(level: ThinkingLevel | string | undefined): { effort?: string } {
   if (!level) return {};
   const norm = String(level).toLowerCase().trim();
   if (norm === "dynamic") return {}; // server default
@@ -386,98 +382,36 @@ export function selectRawArguments(startText: string, deltaText: string): string
 }
 
 // ---------------------------------------------------------------------------
-// Generation controls (maxOutputTokens / stop / seed)
+// Generation controls (maxOutputTokens)
 // ---------------------------------------------------------------------------
 
 /** Canonical generation controls as carried on `ProviderRequestOptions`. */
 export interface GenerationParams {
   maxOutputTokens?: number;
-  stop?: string[];
-  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. */
-export function normalizeStop(stop: string | string[] | undefined): string[] | undefined {
-  const list = (Array.isArray(stop) ? stop : stop === undefined ? [] : [stop]).filter(
-    (s): s is string => typeof s === "string" && s.length > 0
-  );
-  return list.length > 0 ? list : undefined;
+// The output-token cap as a whole number above zero, else undefined; in: the three generation-param mappers, out: their wire field.
+function outputTokenCap(params: GenerationParams | undefined): number | undefined {
+  const n = params?.maxOutputTokens;
+  return typeof n === "number" && Number.isFinite(n) && n > 0 ? Math.floor(n) : undefined;
 }
 
-/**
- * Standard Chat Completions fields (OpenRouter + generic compat endpoints):
- * `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, 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.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;
+/** Chat Completions (OpenRouter + generic compat endpoints): `max_tokens`, only when the caller set it, so strict endpoints never see anything unasked. */
+export function mapGenerationParamsToChat(params: GenerationParams | undefined): { max_tokens?: number } {
+  const cap = outputTokenCap(params);
+  return cap === undefined ? {} : { max_tokens: cap };
 }
 
-// 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({
-      provider,
-      capability: "stop sequences",
-      requested: `${params.stop.join("|")} (${modelRef})`,
-      reason: `the ${reasonSuffix} defines no stop-sequence parameter.`,
-      fallback: "no stop sequences (the model decides when to stop)",
-    });
-  }
-  if (finiteNumber(params.seed)) {
-    emitProviderWarning({
-      provider,
-      capability: "seed",
-      requested: `${params.seed} (${modelRef})`,
-      reason: `the ${reasonSuffix} defines no seed parameter.`,
-      fallback: "non-deterministic sampling",
-    });
-  }
+/** OpenAI Responses: `max_output_tokens`. */
+export function mapGenerationParamsToOpenAI(params: GenerationParams | undefined): { max_output_tokens?: number } {
+  const cap = outputTokenCap(params);
+  return cap === undefined ? {} : { max_output_tokens: cap };
 }
 
-/** OpenAI Responses: `max_output_tokens` is native; `stop` and `seed` do not exist on this wire (warn + drop). */
-export function mapGenerationParamsToOpenAI(
-  params: GenerationParams | undefined,
-  modelRef: string
-): { max_output_tokens?: number } {
-  if (!params) return {};
-  warnUnsupportedStopSeed("openai", modelRef, params, "OpenAI Responses API");
-  return finiteNumber(params.maxOutputTokens) && params.maxOutputTokens > 0
-    ? { max_output_tokens: Math.floor(params.maxOutputTokens) }
-    : {};
-}
-
-/** Google Interactions `generation_config`: `max_output_tokens` is documented; `stop` and `seed` are not (warn + drop). */
-export function mapGenerationParamsToGoogle(
-  params: GenerationParams | undefined,
-  modelRef: string
-): { max_output_tokens?: number } {
-  if (!params) return {};
-  warnUnsupportedStopSeed("google", modelRef, params, "Gemini Interactions API");
-  return finiteNumber(params.maxOutputTokens) && params.maxOutputTokens > 0
-    ? { max_output_tokens: Math.floor(params.maxOutputTokens) }
-    : {};
+/** Google Interactions `generation_config`: `max_output_tokens`. */
+export function mapGenerationParamsToGoogle(params: GenerationParams | undefined): { max_output_tokens?: number } {
+  const cap = outputTokenCap(params);
+  return cap === undefined ? {} : { max_output_tokens: cap };
 }
 
 // ---------------------------------------------------------------------------
@@ -488,12 +422,7 @@ export function mapGenerationParamsToGoogle(
 function isZodLike(value: unknown): boolean {
   if (!value || typeof value !== "object") return false;
   const v = value as Record<string, unknown>;
-  return (
-    typeof v["safeParse"] === "function" ||
-    typeof v["parse"] === "function" ||
-    "_def" in v ||
-    "~standard" in v
-  );
+  return typeof v["safeParse"] === "function" || typeof v["parse"] === "function" || "_def" in v || "~standard" in v;
 }
 
 // True when a plain object has JSON Schema keywords; in: structured-output normalization, out: a boolean.
@@ -575,7 +504,9 @@ export function normalizeStructuredOutput(output: unknown): StructuredOutputSpec
  * present (bare Zod schema or `{ schema: Zod }`). Used by the loop for
  * post-parse validation; `undefined` means JSON-parse only.
  */
-export function extractOutputValidator(output: unknown): { safeParse: (v: unknown) => { success: boolean; data?: unknown; error?: { message: string } } } | undefined {
+export function extractOutputValidator(
+  output: unknown
+): { safeParse: (v: unknown) => { success: boolean; data?: unknown; error?: { message: string } } } | undefined {
   if (!output) return undefined;
   if (isZodLike(output) && typeof (output as { safeParse?: unknown }).safeParse === "function") {
     return output as { safeParse: (v: unknown) => { success: boolean; data?: unknown; error?: { message: string } } };
@@ -637,9 +568,17 @@ export function parseStructuredOutput(text: string, output: unknown): unknown {
  * Maps a normalized spec onto OpenAI Responses `text.format`.
  * `{ type: json_schema, name, schema, strict }` (docs: responses/create).
  */
-export function mapOutputToOpenAI(
-  spec: StructuredOutputSpec | undefined
-): { format: { type: "json_schema"; name: string; schema: Record<string, unknown>; strict: boolean; description?: string } } | undefined {
+export function mapOutputToOpenAI(spec: StructuredOutputSpec | undefined):
+  | {
+      format: {
+        type: "json_schema";
+        name: string;
+        schema: Record<string, unknown>;
+        strict: boolean;
+        description?: string;
+      };
+    }
+  | undefined {
   if (!spec) return undefined;
   return {
     format: {
@@ -670,8 +609,10 @@ export function mapOutputToGoogle(
 }
 
 /** Chat Completions `response_format` wire shape (OpenRouter + compat). */
-export type ChatCompletionsResponseFormat =
-  | { type: "json_schema"; json_schema: { name: string; schema: Record<string, unknown>; strict: boolean; description?: string } };
+export type ChatCompletionsResponseFormat = {
+  type: "json_schema";
+  json_schema: { name: string; schema: Record<string, unknown>; strict: boolean; description?: string };
+};
 
 /**
  * Maps a normalized spec onto Chat Completions `response_format`.

package/src/scheduler/architecture.md

@@ -2,14 +2,15 @@
 
 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, dead-owner recovery, heartbeats, cook/deliver state machine, and the public functions (`createScheduledAction`, `list/update/run/skip/deleteScheduledAction`). |
-| `store.ts` | Disk layer under `<home>/scheduled/`: `<id>/task.json`, `<id>/delivery.json`, run files, one short mutex per action; 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. |
+| 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, dead-owner recovery, heartbeats, cook/deliver state machine, and the public functions (`createScheduledAction`, `list/update/run/skip/deleteScheduledAction`). |
+| `store.ts`                         | Disk layer under `<home>/scheduled/`: `<id>/task.json`, `<id>/delivery.json`, run files, one short mutex per action; 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 `<id>/delivery.json`, then `<id>/task.json`. A crash in between is repaired by the dead-owner recovery (`recoverCooking`, at start and every 15 s): the delivery is rebuilt from the run file, or the run is marked `missed` when no run file exists.
 - `startCook` advances the next times BEFORE the run starts; a run still cooking when the next is due is skipped, never stacked.

package/src/scheduler/scheduled-actions.md

@@ -3,6 +3,7 @@ Schedules a sub-agent (a "scheduled action") to run LATER, once or on repeat, on
 Call get_datetime first whenever you create or reschedule, then pick DD from today's date.
 
 COMMANDS (one tool, the `command` field)
+
 - create: schedule a new action. Needs instructions, task and scheduled_action.{name, id, timeToDeliver, meridiem, startCookingInAdvance}. Optional: role, tools, timeoutMs, scheduled_action.repeatEvery, scheduled_action.retries, scheduled_action.onMissed.
 - list: every action with its metadata and state (waiting, cooking, missed, done).
 - get: one action by `id`, with its latest run result.
@@ -12,6 +13,7 @@ COMMANDS (one tool, the `command` field)
 - skip: ignore a missed run of `id` and wait for the next scheduled time.
 
 SCHEDULED_ACTION FIELDS
+
 - name: human label.
 - id: lowercase kebab-case, at most 48 characters, e.g. "daily-ai-brief". The SDK appends 6 characters ("daily-ai-brief-d64aj2"); use that full id in every later command.
 - timeToDeliver: "DD:HH:MM". DD = days from today (00 today, 01 tomorrow, 55 = 55 days ahead). HH:MM = clock time on a 12-hour clock, HH 01-12.
@@ -30,12 +32,14 @@ Weekly report, every Monday at 9:00 AM (use get_datetime to count the days to th
 {"command":"create","instructions":"You review a codebase and report its health.","task":"Report test health, open risks and notable changes this week.","scheduled_action":{"name":"Weekly Codebase Health Report","id":"weekly-code-health","timeToDeliver":"03:09:00","meridiem":"AM","startCookingInAdvance":"00:02:00","repeatEvery":"07:00:00"}}
 
 TIMING ADVICE (do not guess; talk to the user)
+
 - A run must finish before the next one is due, so startCookingInAdvance must be shorter than repeatEvery.
 - Pick the lead time from the job: a quick lookup fits the 10-minute lead ("00:00:10"); research with many tools needs much more.
 - If the job looks too heavy for the gap the user asked for, do not schedule it blindly. Say so and suggest a wider gap, an earlier start, or a lighter task.
 - A run still cooking when the next one is due is skipped, never stacked, so a gap that is too small means lost runs.
 
 RULES
+
 - Each run starts blank and remembers nothing from earlier runs: put everything the worker needs in instructions and task.
 - Results go to files, not into this chat. Tell the user the action is scheduled and when it will be delivered.
 - Never put secrets in instructions or task: they are stored as plain text.