agent-accelerator 0.4.5 → 0.5.0

package/src/providers/shared.ts

@@ -6,8 +6,11 @@
  * across the four REST transports, plus timeout/signal and id helpers.
  */
 import { toConciseProviderError } from "../utils/errors.ts";
+import { withRetries } from "../utils/retry.ts";
+import { redactHeadersCentral } from "../utils/cache.ts";
+import { TRUNCATED_ARGS_KEY, isTruncatedArguments } from "../types/tool.ts";
 
-/** Parses a JSON tool-argument string; non-objects degrade to `{ raw }`. */
+/** Parses a JSON tool-argument string; non-objects degrade to the truncated-arguments marker. */
 export function parseArguments(raw: string | undefined): Record<string, unknown> {
   if (!raw) return {};
   try {
@@ -15,9 +18,9 @@ export function parseArguments(raw: string | undefined): Record<string, unknown>
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
       return parsed as Record<string, unknown>;
     }
-    return { raw };
+    return { [TRUNCATED_ARGS_KEY]: raw };
   } catch {
-    return { raw };
+    return { [TRUNCATED_ARGS_KEY]: raw };
   }
 }
 
@@ -30,17 +33,13 @@ export function normalizeThinkingParts(parts: string[]): string | undefined {
 }
 
 /**
- * Redacts secret-bearing headers for the raw audit trail. Superset of the
- * four adapter versions: `authorization` (any case) and `x-goog-api-key` are
- * redacted; all other headers pass through untouched.
+ * Redacts secret-bearing headers for the raw audit trail via the central
+ * deny-list: any header whose NAME contains key / token / secret / cookie /
+ * authorization (so `x-api-key`, `api-key`, `cf-aig-authorization` …), plus any
+ * value that looks like a credential. Everything else passes through.
  */
 export function redactedHeaders(headers: Record<string, string>): Record<string, string> {
-  const out: Record<string, string> = {};
-  for (const [k, v] of Object.entries(headers)) {
-    const lower = k.toLowerCase();
-    out[k] = lower === "authorization" || lower === "x-goog-api-key" ? "[REDACTED]" : v;
-  }
-  return out;
+  return redactHeadersCentral(headers) as Record<string, string>;
 }
 
 /**
@@ -92,6 +91,30 @@ export function incompleteStreamError(provider: string, modelId: string): Error
   return err;
 }
 
+/**
+ * True when an error signals an evicted/invalid chained interaction
+ * (Google Interactions `404` / `{code: not_found}` on REST, `{event_type:
+ * error, error: {code: not_found}}` on SSE). Structured-data only: HTTP
+ * status, `code`, or `errorType` — never message text.
+ */
+export function isNotFoundChainError(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const err = error as Record<string, unknown>;
+  const status = Number(
+    (err["status"] as number | undefined) ??
+      (err["statusCode"] as number | undefined) ??
+      ((err["response"] as Record<string, unknown> | undefined)?.["status"] as number | undefined) ??
+      NaN
+  );
+  if (status === 404) return true;
+  const code = String(
+    (err["code"] as string | undefined) ??
+      (err["errorType"] as string | undefined) ??
+      ""
+  ).toLowerCase();
+  return code === "not_found";
+}
+
 /** Per-request timeout ms from provider options (Q-22). */
 export function timeoutFor(options: { timeoutMs?: number } | undefined): number | undefined {
   const t = (options as { timeoutMs?: unknown } | undefined)?.timeoutMs;
@@ -152,11 +175,9 @@ export function hasAuthHeader(headers: Record<string, string> | undefined): bool
   return false;
 }
 
-/** True for truncated streamed tool args (`{ raw }` marker from `parseStreamedToolArguments`). */
+/** True for truncated streamed tool args (the `__truncated_raw` marker from `parseStreamedToolArguments`). */
 export function hasTruncatedToolArguments(args: unknown): boolean {
-  if (!args || typeof args !== "object" || Array.isArray(args)) return false;
-  const keys = Object.keys(args as Record<string, unknown>);
-  return keys.length === 1 && keys[0] === "raw" && typeof (args as Record<string, unknown>).raw === "string";
+  return isTruncatedArguments(args);
 }
 
 /** Short hash for tool-ID clamping (FNV-1a, 8 hex chars, no deps). */
@@ -188,3 +209,76 @@ export function clampToolCallId(id: string): string {
   const prefix = callId.slice(0, Math.max(1, 40 - hash.length - 1));
   return `${prefix}_${hash}`;
 }
+
+/** Plain lower-cased header record from a fetch `Headers` object. */
+export function headersToRecord(headers: Headers): Record<string, string> {
+  const out: Record<string, string> = {};
+  headers.forEach((v, k) => {
+    out[k] = v;
+  });
+  return out;
+}
+
+/**
+ * Parses a rate-limit hint from response headers into milliseconds:
+ * `retry-after-ms`, then `retry-after` (delta-seconds or HTTP-date).
+ * Returns undefined when absent or unparseable.
+ */
+export function parseRetryAfterMs(headers: Record<string, string> | undefined, now = Date.now()): number | undefined {
+  if (!headers) return undefined;
+  const get = (name: string): string | undefined => {
+    for (const [k, v] of Object.entries(headers)) if (k.toLowerCase() === name) return v;
+    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));
+  const ra = get("retry-after");
+  if (ra === undefined || ra.trim() === "") return undefined;
+  const secs = Number(ra);
+  if (Number.isFinite(secs)) return secs >= 0 ? Math.round(secs * 1000) : undefined;
+  const at = Date.parse(ra);
+  return Number.isFinite(at) ? Math.max(0, at - now) : undefined;
+}
+
+/**
+ * Opens an SSE response, retrying transient failures (429/5xx/network) BEFORE
+ * any byte is consumed, so a streaming caller gets the same resilience as
+ * `generate()`. Once this resolves the stream is live and never retried.
+ * `onHttpError` must throw (usually the adapter's concise `throwIfError`).
+ */
+export function openStreamResponse(args: {
+  fetchOnce: () => Promise<Response>;
+  onHttpError: (res: Response, bodyText: string) => void;
+  noBodyError: () => Error;
+  retry: ReturnType<typeof retryOptionsFrom>;
+  signal: AbortSignal;
+  label: { providerId: string; modelId: string };
+}): Promise<Response> {
+  return withRetries(
+    async () => {
+      const res = await args.fetchOnce();
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        args.onHttpError(res, text);
+      }
+      if (!res.body) throw args.noBodyError();
+      return res;
+    },
+    { ...args.retry, signal: args.signal, label: args.label }
+  );
+}
+
+/** 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 } {
+  return {
+    maxRetries: options?.maxRetries,
+    maxRetryDelayMs: options?.maxRetryDelayMs,
+    baseDelayMs: options?.retryBaseDelayMs,
+    retryBudgetMs: options?.retryBudgetMs,
+  };
+}

package/src/providers.ts

@@ -13,6 +13,8 @@ import type { CacheConfig, ServiceTier, ThinkingLevel } from "./types/core.ts";
 import type { StructuredOutputSpec } from "./types/model.ts";
 import { zodToJsonSchema } from "./tools/schema.ts";
 import { ValidationError } from "./types/errors.ts";
+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 =
@@ -50,11 +52,19 @@ export function emitProviderWarning(options: {
   if (emittedWarnings.has(key)) return;
   emittedWarnings.add(key);
   const requested = options.requested ? ` (requested: "${options.requested}")` : "";
-  // Leading newline: warnings fire at the start of a turn's request build,
-  // when the previous turn's streamed text may have left the terminal cursor
-  // mid-line. Without it the warning glues onto streamed output.
-  // Q-41 dual: telemetry bus (new) + console.warn (compat for existing captureWarnings tests; /cli logger replaces in 0.5).
-  { const msg = `[Agent Accelerator] WARNING [${options.provider}] ${options.capability}${requested}: ${options.reason} Using ${options.fallback} instead.`; try { (globalThis as any).__agentAccelTelemetry?.emitWarning?.({ code: "provider_warning", provider: options.provider, capability: options.capability, message: msg }); } catch {} try { (globalThis as any).__agentAccelWarnSink?.(msg, options); } catch {} try { console.warn(msg); } catch {} }
+  // Primary channel: the telemetry bus (code `provider_warning`). The legacy
+  // global sink and `console.warn` remain for existing capture-based tests and
+  // CLIs that predate the bus.
+  const msg = `[Agent Accelerator] WARNING [${options.provider}] ${options.capability}${requested}: ${options.reason} Using ${options.fallback} instead.`;
+  telemetryBus.emitWarning("provider_warning", msg, {
+    provider: options.provider,
+    capability: options.capability,
+    requested: options.requested,
+    reason: options.reason,
+    fallback: options.fallback,
+  });
+  try { (globalThis as any).__agentAccelWarnSink?.(msg, options); } catch {}
+  try { console.warn(msg); } catch {}
 }
 
 /** Clears deduped-warning state (mainly for tests). */
@@ -490,7 +500,110 @@ export function parseStreamedToolArguments(startText: string, deltaText: string)
       // try next candidate
     }
   }
-  return { raw: startText + deltaText };
+  return { [TRUNCATED_ARGS_KEY]: startText + deltaText };
+}
+
+/**
+ * Returns the wire string that actually parsed in
+ * {@link parseStreamedToolArguments} (identical candidate trial order), so
+ * `rawArguments` audit trails never store concatenation artifacts like
+ * `"{}{...}"` (empty start payload + complete delta). Falls back to the raw
+ * concatenation when nothing parses, preserving the truncated-call marker
+ * path (`{ __truncated_raw }`, never executed).
+ *
+ * @example `selectRawArguments("{}", '{"location":"Paris"}') // '{"location":"Paris"}'`
+ */
+export function selectRawArguments(startText: string, deltaText: string): string {
+  const candidates = [startText + deltaText, deltaText, startText].filter((c) => c && c.trim());
+  for (const candidate of candidates) {
+    try {
+      const parsed: unknown = JSON.parse(candidate);
+      if (isPlainObject(parsed)) return candidate;
+    } catch {
+      // try next candidate
+    }
+  }
+  return startText + deltaText;
+}
+
+// ---------------------------------------------------------------------------
+// Generation controls (maxOutputTokens / stop / seed)
+// ---------------------------------------------------------------------------
+
+/** Canonical generation controls as carried on `ProviderRequestOptions`. */
+export interface GenerationParams {
+  maxOutputTokens?: number;
+  stop?: string[];
+  seed?: number;
+}
+
+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;
+}
+
+/**
+ * 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): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (!params) return out;
+  if (finiteNumber(params.maxOutputTokens) && params.maxOutputTokens > 0) out["max_tokens"] = Math.floor(params.maxOutputTokens);
+  if (params.stop && params.stop.length > 0) out["stop"] = params.stop;
+  if (finiteNumber(params.seed)) out["seed"] = Math.floor(params.seed);
+  return out;
+}
+
+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` 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) }
+    : {};
 }
 
 // ---------------------------------------------------------------------------

package/src/scheduler/scheduled-actions.md

@@ -0,0 +1,41 @@
+Schedules a sub-agent (a "scheduled action") to run LATER, once or on repeat, on its own. Every run starts blank, does its task with the worker tools, and saves its answer to a file. It does NOT reply in this chat. Use it for deliveries such as "a research brief every day at 7:00 AM" or "a codebase health report every Monday at 9:00 AM".
+
+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.
+- list: every action with its metadata and state (waiting, cooking, missed, done).
+- get: one action by `id`, with its latest run result.
+- update: change instructions, task, tools, timeoutMs, role or any scheduled_action field of the action `id`.
+- kill: delete the action `id` for good. If the answer says it is running, ask the user before retrying with force: true. purge: true also deletes its past run files.
+- run_now: run the action `id` immediately, outside its schedule. Also fixes a missed run.
+- 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.
+- meridiem: "AM" or "PM" for timeToDeliver.
+- startCookingInAdvance: "DD:HH:MM" as a duration (HH 00-23): how long before delivery the run starts. "00:00:10" = 10 minutes, "00:01:00" = 1 hour.
+- repeatEvery (optional): "DD:HH:MM" gap between deliveries. "01:00:00" = every day, "07:00:00" = every week. Omit to run once.
+- retries (optional): extra attempts if a run fails, used only while there is still time before delivery. Default 0.
+
+EXAMPLES
+Daily brief, first delivery tomorrow at 7:00 AM, starting 30 minutes ahead:
+{"command":"create","instructions":"You write a short, sourced AI research brief.","task":"Summarize the most important AI news of the last day in 5 bullets.","scheduled_action":{"name":"Daily AI Research Brief","id":"daily-ai-brief","timeToDeliver":"01:07:00","meridiem":"AM","startCookingInAdvance":"00:00:30","repeatEvery":"01:00:00"}}
+
+Weekly report, every Monday at 9:00 AM (use get_datetime to count the days to the next Monday), starting 2 hours ahead:
+{"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.
+- Actions run only while the host program is running.
+- Worker tools you may grant through `tools`: {{TOOLS}}.