agent-accelerator 0.5.6 → 0.5.8

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,22 @@
+# 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/`: `<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`. 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`.
+- Several processes may share a home (the file store is safe for it; the home lock is lifted in a later change of this release). Ownership: a process only starts, delivers or recovers actions whose Agent it registered. An action nobody here owns is left alone until its delivery time passed with no run started, then marked `missed` (`no_agent`).
+- Exactly once: a scheduled start re-checks under the action's mutex that it is still `waiting` and due; `markMissed` only changes the state the caller saw; a delivery is emitted only by the process that removed its entry from `delivery.json`.
+- A run in flight keeps `<id>/.heartbeat` (pid, host, token; mtime refreshed every 5 s, stale after 60 s), written before the record shows `cooking`. A cooking action whose owner is dead (pid gone, stale, or none) is recovered by a live process that owns its Agent, at start and every 15 s. `delete` of a run another live process is cooking is refused, even with `force`.
+- 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}`.