@providerkit/core 0.8.1 → 0.10.0

package/src/rate-limit.ts

@@ -39,6 +39,7 @@ export interface RateLimitReset {
 }
 
 const RETRY_AFTER = "retry-after";
+const RETRY_AFTER_MS = "retry-after-ms";
 const UNIFIED_5H = "anthropic-ratelimit-unified-5h-";
 const UNIFIED_7D = "anthropic-ratelimit-unified-7d-";
 
@@ -74,27 +75,50 @@ function unixSecondsToMs(value: string | null): number | undefined {
   return n === undefined ? undefined : n * 1000;
 }
 
+/** Matches Go-style duration strings like "2m59.56s", "7.66s", "500ms", "1h30m". */
+const DURATION_PATTERN =
+  /^(?:(\d+(?:\.\d+)?)h)?(?:(\d+(?:\.\d+)?)m(?!s))?(?:(\d+(?:\.\d+)?)m?s)?$/i;
+
+function parseDurationMs(text: string): number | undefined {
+  const match = DURATION_PATTERN.exec(text.trim());
+  if (!match || !match.slice(1).some(Boolean)) return undefined;
+  const hours = Number(match[1]) || 0;
+  const minutes = Number(match[2]) || 0;
+  const seconds = Number(match[3]) || 0;
+  const isMs = text.toLowerCase().endsWith("ms");
+  const secMs = isMs ? seconds : seconds * 1000;
+  const total = Math.round(hours * 3_600_000 + minutes * 60_000 + secMs);
+  return total >= 0 ? total : undefined;
+}
+
 /** Absolute reset time from a header that spells it either way: epoch seconds
- *  (the unified reset, most gateways) or an RFC 3339 / HTTP-date string (the
- *  API-key reset headers). The digit test runs first because `Date.parse("120")`
- *  is not a rejection — it is the year 120, two millennia in the past. */
+ *  (the unified reset, most gateways), Go-style duration ("2m59s" from OpenAI),
+ *  or an RFC 3339 / HTTP-date string (the API-key reset headers). */
 function resetHeaderMs(value: string | null, now: number): number | undefined {
   if (!value) return undefined;
-  if (/^\d+$/.test(value)) {
-    const seconds = Number(value);
+  const trimmed = value.trim();
+  if (/^\d+$/.test(trimmed)) {
+    const seconds = Number(trimmed);
     return seconds > EPOCH_SECONDS_FLOOR ? seconds * 1000 : now + seconds * 1000;
   }
-  const at = Date.parse(value);
+  const duration = parseDurationMs(trimmed);
+  if (duration !== undefined) {
+    return now + duration;
+  }
+  const at = Date.parse(trimmed);
   return Number.isNaN(at) ? undefined : at;
 }
 
-/** `retry-after` is delay-seconds, but RFC 9110 also allows an absolute date,
- *  and both forms occur across the providers this package speaks to. */
+/** `retry-after` is delay-seconds, Go-style duration ("60s"), or an absolute
+ *  HTTP date, and all three occur across providers this package speaks to. */
 function parseRetryAfter(value: string | null, now: number): number | undefined {
   if (!value) return undefined;
-  const n = Number(value);
+  const trimmed = value.trim();
+  const n = Number(trimmed);
   if (Number.isFinite(n) && n >= 0) return n * 1000;
-  const at = Date.parse(value);
+  const duration = parseDurationMs(trimmed);
+  if (duration !== undefined) return duration;
+  const at = Date.parse(trimmed);
   return Number.isNaN(at) ? undefined : Math.max(0, at - now);
 }
 
@@ -110,7 +134,10 @@ function parseRetryAfter(value: string | null, now: number): number | undefined
 export function parseRateLimitReset(headers: Headers, now = Date.now()): RateLimitReset {
   const result: RateLimitReset = {};
 
-  const after = parseRetryAfter(headers.get(RETRY_AFTER), now);
+  // `retry-after-ms` is Anthropic's millisecond spelling of the same header;
+  // when both ride a response the coarser one is the same deadline rounded.
+  const afterMs = numeric(headers.get(RETRY_AFTER_MS));
+  const after = afterMs ?? parseRetryAfter(headers.get(RETRY_AFTER), now);
   if (after !== undefined) {
     result.retryAfterMs = after;
     result.resetAtMs = now + after;
@@ -176,9 +203,31 @@ function jsonSeconds(value: unknown): number | undefined {
   return Number.isFinite(n) ? n : undefined;
 }
 
+const PROSE_RETRY_PATTERNS = [
+  /try again in (\d+(?:\.\d+)?)\s*(s(?:ec(?:ond)?s?)?|m(?:in(?:ute)?s?)?|h(?:(?:ou)?rs?)?)/i,
+  /retry after (\d+(?:\.\d+)?)\s*(s(?:ec(?:ond)?s?)?|m(?:in(?:ute)?s?)?|h(?:(?:ou)?rs?)?)/i,
+  /resets? (?:in|after) (\d+(?:\.\d+)?)\s*(s(?:ec(?:ond)?s?)?|m(?:in(?:ute)?s?)?|h(?:(?:ou)?rs?)?)/i,
+  /retry[- ]after[:\s]+(\d+(?:\.\d+)?)\s*(s(?:ec(?:ond)?s?)?|m(?:in(?:ute)?s?)?|h(?:(?:ou)?rs?)?)?/i,
+];
+
+function parseProseRetryMs(text: string): number | undefined {
+  for (const pattern of PROSE_RETRY_PATTERNS) {
+    const match = text.match(pattern);
+    if (!match?.[1]) continue;
+    const val = Number.parseFloat(match[1]);
+    if (!Number.isFinite(val) || val <= 0) continue;
+    const unit = (match[2] ?? "s").toLowerCase();
+    const multiplier = unit.startsWith("h") ? 3_600_000 : unit.startsWith("m") ? 60_000 : 1_000;
+    return Math.ceil(val * multiplier);
+  }
+  return undefined;
+}
+
 /**
  * ChatGPT's codex backend puts the reset IN THE 429 BODY, not the headers:
  * `{"error":{"type":"usage_limit_reached","resets_at":1788801754,"resets_in_seconds":2501465}}`.
+ * Other providers and gateways (LiteLLM, Cloudflare, Ollama) report countdowns in prose:
+ * `Rate limit exceeded. Try again in 20s.`
  * The window name is inferred from the wait itself, and only past the floor
  * above — a sub-minute retry is a throttle, not a subscription window.
  */
@@ -187,33 +236,46 @@ export function parseUsageLimitBody(bodyText: string, now = Date.now()): RateLim
   try {
     body = JSON.parse(bodyText);
   } catch {
-    return {};
+    body = undefined;
   }
-  if (typeof body !== "object" || body === null) return {};
-  // The fields sit under `error` on the documented shape and at the top level
-  // on some gateway relays of it. Both are read rather than guessed between.
-  const source = (body as Record<string, unknown>).error;
-  const error =
-    typeof source === "object" && source !== null
-      ? (source as Record<string, unknown>)
-      : (body as Record<string, unknown>);
-
-  const inSeconds = jsonSeconds(error.resets_in_seconds);
-  const atSeconds = jsonSeconds(error.resets_at);
-  const waitMs =
-    inSeconds !== undefined && inSeconds >= 0
-      ? inSeconds * 1000
-      : atSeconds !== undefined && atSeconds > 0
-        ? Math.max(0, atSeconds * 1000 - now)
-        : undefined;
-  if (waitMs === undefined) return {};
-
-  const result: RateLimitReset = { retryAfterMs: waitMs, resetAtMs: now + waitMs };
-  if (waitMs > WINDOW_FLOOR_MS) {
-    result.window =
-      waitMs <= FIVE_HOUR_MAX_MS ? "5h" : waitMs <= WEEKLY_MAX_MS ? "weekly" : "monthly";
+
+  if (typeof body === "object" && body !== null) {
+    const source = (body as Record<string, unknown>).error;
+    const error =
+      typeof source === "object" && source !== null
+        ? (source as Record<string, unknown>)
+        : (body as Record<string, unknown>);
+
+    const inSeconds = jsonSeconds(error.resets_in_seconds);
+    const atSeconds = jsonSeconds(error.resets_at);
+    const waitMs =
+      inSeconds !== undefined && inSeconds >= 0
+        ? inSeconds * 1000
+        : atSeconds !== undefined && atSeconds > 0
+          ? Math.max(0, atSeconds * 1000 - now)
+          : undefined;
+    if (waitMs !== undefined) {
+      const result: RateLimitReset = { retryAfterMs: waitMs, resetAtMs: now + waitMs };
+      if (waitMs > WINDOW_FLOOR_MS) {
+        result.window =
+          waitMs <= FIVE_HOUR_MAX_MS ? "5h" : waitMs <= WEEKLY_MAX_MS ? "weekly" : "monthly";
+      }
+      return result;
+    }
   }
-  return result;
+
+  // If structured JSON did not yield a reset, check prose wording
+  const waitMs = parseProseRetryMs(bodyText);
+  if (waitMs !== undefined) {
+    const result: RateLimitReset = { retryAfterMs: waitMs, resetAtMs: now + waitMs };
+    if (waitMs > WINDOW_FLOOR_MS) {
+      result.window =
+        waitMs <= FIVE_HOUR_MAX_MS ? "5h" : waitMs <= WEEKLY_MAX_MS ? "weekly" : "monthly";
+    }
+    return result;
+  }
+
+  return {};
 }
 
 /** Read both places an endpoint can report its reset. A short Retry-After is

package/src/retry.ts

@@ -13,7 +13,13 @@
 //
 //  3. Honour the provider's own number. When it says `Retry-After: 30`, a
 //     one-second backoff is three wasted attempts before the same wait.
-import { classify, isBackupEligible, isTransient, parseRetryAfterMs, ProviderError } from "./errors.ts";
+import {
+  classify,
+  isBackupEligible,
+  isRetryable,
+  parseRetryAfterMs,
+  ProviderError,
+} from "./errors.ts";
 
 export interface RetryOptions {
   /** Total attempts including the first. Default 3. */
@@ -83,7 +89,7 @@ function delayFor(err: unknown, attempt: number, opts: RetryOptions): number | n
   return backoffMs(attempt, opts.baseDelayMs ?? DEFAULT_BASE_DELAY_MS, cap);
 }
 
-const defaultShouldRetry = (err: unknown): boolean => isTransient(classify(err));
+const defaultShouldRetry = (err: unknown, _attempt: number): boolean => isRetryable(err);
 
 /**
  * Run `fn`, retrying transient failures with backoff. For one-shot calls —

package/src/schema.ts

@@ -133,3 +133,130 @@ export function isStrictSchema(node: unknown): boolean {
     ([key, value]) => required.has(key) && isStrictSchema(value),
   );
 }
+
+/**
+ * Sanitize a JSON Schema for Google Gemini's REST API.
+ *
+ * Gemini's functionDeclarations schema parser only accepts a strict OpenAPI 3.0 subset.
+ * It rejects:
+ * - Nullable type arrays (`type: ["string", "null"]`), requiring `{ type: "string", nullable: true }`.
+ * - Union types with null (`anyOf: [{ type: "string" }, { type: "null" }]`), requiring `{ type: "string", nullable: true }`.
+ * - Numeric enums (`enum: [1, 2, 3]`), requiring string enums.
+ * - `const: "val"`, requiring `enum: ["val"]`.
+ * - Arrays without `items`, requiring an explicit items schema.
+ * - Unsupported keywords ($schema, definitions, $defs, patternProperties, additionalProperties: true).
+ */
+export function toGeminiToolSchema(node: unknown): Record<string, unknown> {
+  if (!node || typeof node !== "object" || Array.isArray(node)) {
+    return { type: "object", properties: {} };
+  }
+  const schema = { ...(node as Record<string, unknown>) };
+
+  delete schema.$schema;
+  delete schema.$id;
+  delete schema.$ref;
+  delete schema.definitions;
+  delete schema.$defs;
+  delete schema.patternProperties;
+
+  if (schema.additionalProperties === true) {
+    delete schema.additionalProperties;
+  }
+
+  if ("const" in schema && !("enum" in schema)) {
+    schema.enum = [String(schema.const)];
+    delete schema.const;
+  }
+
+  const union = schema.anyOf ?? schema.oneOf;
+  if (Array.isArray(union)) {
+    const nonNullBranches = union.filter(
+      (b) => typeof b === "object" && b !== null && (b as Record<string, unknown>).type !== "null",
+    );
+    const hasNull = union.some(
+      (b) => typeof b === "object" && b !== null && (b as Record<string, unknown>).type === "null",
+    );
+    if (nonNullBranches.length === 1 && typeof nonNullBranches[0] === "object") {
+      const merged = toGeminiToolSchema(nonNullBranches[0]);
+      if (hasNull) merged.nullable = true;
+      return merged;
+    }
+  }
+
+  if (Array.isArray(schema.type)) {
+    const types = schema.type as string[];
+    const hasNull = types.includes("null");
+    const nonNull = types.filter((t) => t !== "null");
+    schema.type = nonNull[0] ?? "string";
+    if (hasNull) schema.nullable = true;
+  }
+
+  if (Array.isArray(schema.enum)) {
+    schema.enum = schema.enum.map((val) => String(val));
+  }
+
+  if (schema.type === "array" && !schema.items) {
+    schema.items = { type: "string" };
+  } else if (schema.items && typeof schema.items === "object") {
+    schema.items = toGeminiToolSchema(schema.items);
+  }
+
+  if (schema.properties && typeof schema.properties === "object") {
+    const props = schema.properties as Record<string, unknown>;
+    const sanitizedProps: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(props)) {
+      sanitizedProps[key] = toGeminiToolSchema(val);
+    }
+    schema.properties = sanitizedProps;
+  }
+
+  return schema;
+}
+
+/**
+ * Sanitize a tool's JSON Schema for Anthropic's Messages API.
+ *
+ * Anthropic rejects schemas where the root is an `anyOf` / `oneOf` / `allOf` union,
+ * requiring a root object schema (`{ type: "object", properties: ... }`).
+ */
+export function toAnthropicToolSchema(node: unknown): Record<string, unknown> {
+  if (!node || typeof node !== "object" || Array.isArray(node)) {
+    return { type: "object", properties: {} };
+  }
+  const schema = { ...(node as Record<string, unknown>) };
+
+  delete schema.$schema;
+  delete schema.$id;
+
+  const union = schema.anyOf ?? schema.oneOf;
+  if (Array.isArray(union)) {
+    const mergedProperties: Record<string, unknown> = {};
+    const mergedRequired = new Set<string>();
+    for (const branch of union) {
+      if (typeof branch === "object" && branch !== null) {
+        const b = branch as Record<string, unknown>;
+        if (b.properties && typeof b.properties === "object") {
+          Object.assign(mergedProperties, b.properties);
+        }
+        if (Array.isArray(b.required)) {
+          for (const req of b.required) {
+            if (typeof req === "string") mergedRequired.add(req);
+          }
+        }
+      }
+    }
+    delete schema.anyOf;
+    delete schema.oneOf;
+    schema.type = "object";
+    schema.properties = mergedProperties;
+    if (mergedRequired.size > 0 && !schema.required) {
+      schema.required = Array.from(mergedRequired);
+    }
+  }
+
+  if (!schema.type) {
+    schema.type = "object";
+  }
+
+  return schema;
+}

package/src/tool-args.ts

@@ -85,9 +85,54 @@ function salvageStringFields(raw: string): Record<string, unknown> {
   return out;
 }
 
+/**
+ * Attempt to recover the last valid JSON object from concatenated or prepended JSON
+ * (e.g. `{}{"query":"hello"}` or `{"a":1}{"b":2}`).
+ */
+export function findLastValidJsonObject(raw: string): Record<string, unknown> | null {
+  const trimmed = raw.trim();
+  if (!trimmed.includes("{")) return null;
+
+  let startIdx = trimmed.lastIndexOf("{");
+  while (startIdx >= 0) {
+    const candidate = trimmed.slice(startIdx);
+    try {
+      const parsed: unknown = JSON.parse(candidate);
+      if (isRecord(parsed)) return parsed;
+    } catch {
+      // Keep searching earlier '{'
+    }
+    if (startIdx === 0) break;
+    startIdx = trimmed.lastIndexOf("{", startIdx - 1);
+  }
+  return null;
+}
+
+/**
+ * Normalizes tool call IDs:
+ * 1. Synthesizes a fallback if empty/whitespace.
+ * 2. Clamps oversized IDs (> 64 chars) to avoid ChatGPT Responses 400 errors.
+ */
+export function normalizeToolId(id: string | undefined | null, prefix = "call_pk_"): string {
+  const clean = id?.trim();
+  if (!clean) {
+    return `${prefix}${Math.random().toString(36).slice(2, 10)}`;
+  }
+  if (clean.length > 64) {
+    let hash = 0;
+    for (let i = 0; i < clean.length; i++) {
+      hash = (Math.imul(31, hash) + clean.charCodeAt(i)) | 0;
+    }
+    const hashHex = (hash >>> 0).toString(16).padStart(8, "0");
+    return `${clean.slice(0, 48)}_${hashHex}`;
+  }
+  return clean;
+}
+
 /**
  * Parse a tool call's raw argument string into an object, salvaging what a
- * truncated stream left behind and healing double-escaped text either way.
+ * truncated stream left behind, resolving concatenated JSON, and healing
+ * double-escaped text either way.
  *
  * Never throws: a tool call the model malformed is data the caller decides
  * about, not an exception in the transport.
@@ -98,6 +143,8 @@ export function parseToolArgs(raw: string): Record<string, unknown> {
   try {
     parsed = JSON.parse(raw);
   } catch {
+    const lastObj = findLastValidJsonObject(raw);
+    if (lastObj !== null) return healArgs(lastObj);
     return healArgs(salvageStringFields(raw));
   }
   // A non-object payload is a protocol violation, not a value to pass on.

package/src/transport.ts

@@ -68,9 +68,13 @@ async function errorFor(provider: string, res: Response): Promise<ProviderError>
   const message = text
     ? `${provider} ${res.status}: ${text.slice(0, 500)}`
     : `${provider} ${res.status} ${res.statusText}`;
+  const shouldRetryHeader = res.headers.get("x-should-retry");
+  const shouldRetry =
+    shouldRetryHeader === "false" ? false : shouldRetryHeader === "true" ? true : undefined;
   return new ProviderError(provider, kind, message, {
     status: res.status,
     ...reset,
+    shouldRetry,
     retryAfterMs: retryAfterFromHeaders(res.headers) ?? parseRetryAfterMs({}, text),
     body: text.slice(0, 2_000) || undefined,
   });

package/src/usage.ts

@@ -36,6 +36,19 @@ export function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
   };
 }
 
+/**
+ * Subtract usage `b` from `a`, clamping each field at zero.
+ * Used when an optimistic turn or speculative stream is rolled back.
+ */
+export function subtractUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
+  return {
+    inputTokens: Math.max(0, a.inputTokens - b.inputTokens),
+    cachedInputTokens: Math.max(0, a.cachedInputTokens - b.cachedInputTokens),
+    cacheWriteTokens: Math.max(0, (a.cacheWriteTokens ?? 0) - (b.cacheWriteTokens ?? 0)),
+    outputTokens: Math.max(0, a.outputTokens - b.outputTokens),
+  };
+}
+
 /**
  * USD for one call.
  *
@@ -79,6 +92,14 @@ export class UsageTracker {
     this.saved += (cached * (rate.input - rate.cacheRead)) / 1_000_000;
   }
 
+  subtract(usage: TokenUsage, rate?: ModelRate): void {
+    this.usage = subtractUsage(this.usage, usage);
+    if (!rate) return;
+    this.cost = Math.max(0, this.cost - costUsd(usage, rate));
+    const cached = Math.min(Math.max(0, usage.cachedInputTokens), Math.max(0, usage.inputTokens));
+    this.saved = Math.max(0, this.saved - (cached * (rate.input - rate.cacheRead)) / 1_000_000);
+  }
+
   get totals(): TokenUsage {
     return { ...this.usage };
   }