agent-accelerator 0.4.0 → 0.5.0

package/src/providers.ts

@@ -10,6 +10,11 @@
  * redesigning this abstraction — only new per-provider mappers/adapters.
  */
 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 =
@@ -47,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). */
@@ -357,17 +370,17 @@ export function mapServiceTierToOpenAI(tier: ServiceTier | undefined): "flex" |
 
 /**
  * Applies canonical cache config for OpenAI. Session affinity flows via
- * `prompt_cache_key` (handled by the adapter); explicit retention control
- * lives in `prompt_cache_options` (gpt-5.6+ explicit breakpoints) which is
- * out of scope for the most-important subset, so retention/cachedContentId
- * are UNSUPPORTED: warn and drop. `prompt_cache_retention` is deprecated.
+ * `prompt_cache_key` (handled by the adapter); `long` retention maps to
+ * `prompt_cache_retention: "24h"` when the catalog supports it (handled by
+ * the adapter, pi `api/openai-responses.ts:97` rule). Other explicit
+ * retention modes and `cachedContentId` are UNSUPPORTED: warn and drop.
  */
 export function applyCacheForOpenAI(
   cache: CacheConfig | undefined,
   modelRef: string
 ): void {
   if (!cache) return;
-  if (cache.retention && cache.retention !== "implicit") {
+  if (cache.retention && cache.retention !== "implicit" && cache.retention !== "long") {
     emitProviderWarning({
       provider: "openai",
       capability: "cache retention",
@@ -487,5 +500,356 @@ 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) }
+    : {};
+}
+
+// ---------------------------------------------------------------------------
+// Structured outputs (canonical, pure, no I/O)
+// ---------------------------------------------------------------------------
+
+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
+  );
+}
+
+function looksLikeJsonSchema(value: unknown): boolean {
+  if (!isPlainObject(value)) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v["type"] === "string" ||
+    isPlainObject(v["properties"]) ||
+    Array.isArray(v["anyOf"]) ||
+    Array.isArray(v["oneOf"]) ||
+    Array.isArray(v["allOf"]) ||
+    typeof v["$schema"] === "string" ||
+    isPlainObject(v["$defs"]) ||
+    isPlainObject(v["definitions"])
+  );
+}
+
+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;
+}
+
+function schemaToJsonSchema(schema: unknown, what: string): Record<string, unknown> {
+  if (isZodLike(schema)) {
+    try {
+      const converted = zodToJsonSchema(schema);
+      if (isPlainObject(converted)) return converted;
+    } catch {
+      // fall through to error below
+    }
+  }
+  if (isPlainObject(schema)) return schema as Record<string, unknown>;
+  throw new ValidationError(
+    `[Agent Accelerator] Invalid structured output ${what}: expected a Zod schema, a JSON Schema object, or { name, schema, strict }.`
+  );
+}
+
+/**
+ * Normalizes `AgentConfig.output` into a provider-agnostic spec.
+ *
+ * Accepts a Zod schema, a JSON Schema object, or an explicit
+ * `{ name?, description?, schema, strict? }` wrapper. Returns `undefined`
+ * when no output was requested. Throws `ValidationError` for invalid shapes.
+ *
+ * @example `normalizeStructuredOutput(z.object({ city: z.string() }))`
+ */
+export function normalizeStructuredOutput(output: unknown): StructuredOutputSpec | undefined {
+  if (output === undefined || output === null) return undefined;
+  if (isPlainObject(output) && "schema" in (output as Record<string, unknown>)) {
+    const rec = output as Record<string, unknown>;
+    const schema = schemaToJsonSchema(rec["schema"], "`output.schema`");
+    return {
+      name: sanitizeOutputName(rec["name"]),
+      schema,
+      strict: typeof rec["strict"] === "boolean" ? (rec["strict"] as boolean) : true,
+      ...(typeof rec["description"] === "string" && (rec["description"] as string).trim()
+        ? { description: (rec["description"] as string).trim() }
+        : {}),
+    };
+  }
+  if (isZodLike(output) || looksLikeJsonSchema(output)) {
+    return {
+      name: "structured_output",
+      schema: schemaToJsonSchema(output, "`output`"),
+      strict: true,
+    };
+  }
+  throw new ValidationError(
+    "[Agent Accelerator] Invalid structured output: expected a Zod schema, a JSON Schema object, or { name, schema, strict }."
+  );
+}
+
+/**
+ * Extracts the original Zod validator from a canonical output option, when
+ * 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 {
+  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 } } };
+  }
+  if (isPlainObject(output) && isZodLike((output as Record<string, unknown>)["schema"])) {
+    const inner = (output as Record<string, unknown>)["schema"] as { safeParse?: unknown };
+    if (typeof inner.safeParse === "function") {
+      return inner as { safeParse: (v: unknown) => { success: boolean; data?: unknown; error?: { message: string } } };
+    }
+  }
+  return undefined;
+}
+
+function stripCodeFences(text: string): string {
+  const trimmed = text.trim();
+  const fenced = trimmed.match(/^```(?:json)?\s*\n([\s\S]*?)\n```\s*$/i);
+  if (fenced && typeof fenced[1] === "string") return fenced[1].trim();
+  return trimmed;
+}
+
+/**
+ * Parses and validates a final answer against a canonical output option.
+ * Strips markdown fences, requires valid JSON, then applies the Zod validator
+ * when the original option carried one. Throws `ValidationError` on mismatch.
+ *
+ * @example `parseStructuredOutput('{"city":"Paris"}', z.object({ city: z.string() }))`
+ */
+export function parseStructuredOutput(text: string, output: unknown): unknown {
+  const cleaned = stripCodeFences(typeof text === "string" ? text : String(text ?? ""));
+  if (!cleaned) {
+    throw new ValidationError(
+      "[Agent Accelerator] Structured output validation failed: model returned empty text, expected JSON matching the output schema."
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(cleaned);
+  } catch {
+    throw new ValidationError(
+      `[Agent Accelerator] Structured output validation failed: model text is not valid JSON (${cleaned.slice(0, 120)}).`
+    );
+  }
+  const validator = extractOutputValidator(output);
+  if (validator) {
+    const res = validator.safeParse(parsed);
+    if (!res.success) {
+      const detail = res.error?.message ? ` ${res.error.message}`.slice(0, 500) : "";
+      throw new ValidationError(
+        `[Agent Accelerator] Structured output validation failed: JSON does not match the output schema.${detail}`
+      );
+    }
+    return res.data ?? parsed;
+  }
+  return parsed;
+}
+
+/**
+ * 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 {
+  if (!spec) return undefined;
+  return {
+    format: {
+      type: "json_schema",
+      name: spec.name,
+      schema: spec.schema,
+      strict: spec.strict ?? true,
+      ...(spec.description ? { description: spec.description } : {}),
+    },
+  };
+}
+
+/**
+ * Maps a normalized spec onto Google Interactions `response_format`.
+ * `{ type: text, mime_type: application/json, schema }` (docs: structured-output).
+ */
+export function mapOutputToGoogle(
+  spec: StructuredOutputSpec | undefined
+): { responseFormat: { type: "text"; mime_type: "application/json"; schema: Record<string, unknown> } } | undefined {
+  if (!spec) return undefined;
+  return {
+    responseFormat: {
+      type: "text",
+      mime_type: "application/json",
+      schema: spec.schema,
+    },
+  };
+}
+
+/** 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 } };
+
+/**
+ * Maps a normalized spec onto Chat Completions `response_format`.
+ * `{ type: json_schema, json_schema: { name, schema, strict } }`
+ * (docs: openai completions/create, openrouter parameters).
+ */
+export function mapOutputToOpenRouterChat(
+  spec: StructuredOutputSpec | undefined
+): { response_format: ChatCompletionsResponseFormat } | undefined {
+  if (!spec) return undefined;
+  return {
+    response_format: {
+      type: "json_schema",
+      json_schema: {
+        name: spec.name,
+        schema: spec.schema,
+        strict: spec.strict ?? true,
+        ...(spec.description ? { description: spec.description } : {}),
+      },
+    },
+  };
+}
+
+/**
+ * Maps a normalized spec onto generic compat Chat Completions
+ * `response_format` (same standard shape as OpenRouter Chat).
+ */
+export function mapOutputToCompatChat(
+  spec: StructuredOutputSpec | undefined
+): { response_format: ChatCompletionsResponseFormat } | undefined {
+  return mapOutputToOpenRouterChat(spec);
+}
+
+/**
+ * Builds the emulated structured-output instruction for models without
+ * native `response_format` support (catalog `structured_output: false`).
+ * Appended to the system prompt so the model still targets JSON; the loop
+ * still validates into `AgentResponse.parsed`.
+ *
+ * @example `augmentSystemPromptWithStructuredOutput(sys, spec)`
+ */
+export function buildStructuredOutputInstruction(spec: StructuredOutputSpec): string {
+  return `Return ONLY valid JSON matching this JSON Schema, with no markdown fences, no commentary, no extra text.\nSchema: ${JSON.stringify(spec.schema)}`;
+}
+
+/**
+ * Returns a system prompt with the emulated structured-output instruction
+ * appended (stable per Agent since `output` is agent-level, so prefix-cache
+ * affinity is preserved). No-op when spec is undefined.
+ */
+export function augmentSystemPromptWithStructuredOutput(
+  systemPrompt: string | undefined,
+  spec: StructuredOutputSpec | undefined
+): string | undefined {
+  if (!spec) return systemPrompt;
+  const instruction = `[Structured Output]\n${buildStructuredOutputInstruction(spec)}`;
+  if (!systemPrompt) return instruction;
+  if (systemPrompt.includes("[Structured Output]")) return systemPrompt;
+  return `${systemPrompt}\n\n${instruction}`;
 }

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}}.