agent-accelerator 0.5.8 → 0.6.0

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,20 +2,21 @@
 
 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. |
+| 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`. The startup sweep repairs a crash in between.
+- 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.
 - 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`).
+- Several processes may share a home: scheduled actions take no home lock, only the short per-action mutex (`<id>/.mutex`); the one-process lock is on session folders only. 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()`.

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.