@modelprofile.com/flexharness-agent 8.2.0 → 8.4.0

package/ts_agent/smartagent.retry.ts

@@ -0,0 +1,101 @@
+import * as plugins from './plugins.js';
+
+export type TAgentRetryReason = 'rate_limit' | 'overloaded' | 'unavailable';
+
+/** A failed model call the session engine retries after `delayMs`. */
+export interface IAgentRetryEvent {
+  /** One-based number of this retry within the current model call. */
+  attempt: number;
+  maxAttempts: number;
+  delayMs: number;
+  reason: TAgentRetryReason;
+}
+
+export type TAgentRetryDecision =
+  | { action: 'retry'; delayMs: number; reason: TAgentRetryReason }
+  | { action: 'fail'; error: unknown }
+  | { action: 'not-retryable' };
+
+export interface IAgentRetryState {
+  /** Retries already made for the current model call. */
+  attempt: number;
+  /** Retry delay already spent on the current model call. */
+  retriedMs: number;
+  /** Provider id used when an untyped rate limit has to fail with a typed limit error. */
+  provider: string;
+  now: number;
+}
+
+export const MAX_RETRY_ATTEMPTS = 8;
+/** The longest provider-requested delay honoured; the AI SDK uses the same bound. */
+export const MAX_RETRY_AFTER_MS = 60_000;
+/** The total delay one model call may spend retrying, equal to the full default backoff. */
+export const MAX_RETRY_WINDOW_MS = 150_000;
+
+const RETRY_INITIAL_DELAY_MS = 2000;
+const RETRY_BACKOFF_FACTOR = 2;
+const RETRY_BACKOFF_MAX_DELAY_MS = 30_000;
+
+interface IRetrySignal {
+  reason: TAgentRetryReason;
+  requestedDelayMs?: number;
+}
+
+function backoffDelayMs(attempt: number): number {
+  return Math.min(RETRY_INITIAL_DELAY_MS * RETRY_BACKOFF_FACTOR ** (attempt - 1), RETRY_BACKOFF_MAX_DELAY_MS);
+}
+
+function untypedRetryReason(error: unknown): TAgentRetryReason | undefined {
+  const candidate = error as { status?: number; statusCode?: number } | undefined;
+  const status = candidate?.status ?? candidate?.statusCode;
+  const message = error instanceof Error ? error.message.toLowerCase() : '';
+  if (status === 429 || message.includes('rate limit') || message.includes('too many requests')) {
+    return 'rate_limit';
+  }
+  if (status === 529 || message.includes('overloaded')) return 'overloaded';
+  if (status === 503) return 'unavailable';
+  return undefined;
+}
+
+function readRetrySignal(error: unknown, now: number): IRetrySignal | undefined {
+  if (plugins.isModelLimitError(error)) {
+    const { retryAfterMs, resetsAt } = error.limit;
+    const requestedDelayMs = retryAfterMs ?? (resetsAt === undefined ? undefined : Math.max(0, resetsAt - now));
+    return { reason: 'rate_limit', ...(requestedDelayMs === undefined ? {} : { requestedDelayMs }) };
+  }
+  const reason = untypedRetryReason(error);
+  if (reason === undefined) return undefined;
+  const failure = error as { responseHeaders?: Record<string, string>; headers?: Record<string, string> };
+  const requestedDelayMs = plugins.readRetryAfterMs(failure.responseHeaders ?? failure.headers, now);
+  return { reason, ...(requestedDelayMs === undefined ? {} : { requestedDelayMs }) };
+}
+
+/** The error a rate limit fails with when its retry time lies beyond the retry bounds. */
+function overdueLimitError(error: unknown, signal: IRetrySignal, state: IAgentRetryState): unknown {
+  if (plugins.isModelLimitError(error) || signal.reason !== 'rate_limit' || signal.requestedDelayMs === undefined) {
+    return error;
+  }
+  const limit = plugins.createModelLimitInfo(
+    { kind: 'rate_limit', provider: state.provider, retryAfterMs: signal.requestedDelayMs },
+    state.now,
+  );
+  // an empty or overlong provider id cannot describe a limit, so the provider's own error stays
+  return plugins.isModelLimitInfo(limit) ? new plugins.ModelLimitError(limit, { cause: error }) : error;
+}
+
+/**
+ * Decides whether a failed model call is retried. Usage limits never are; transient limits wait for
+ * the provider's delay up to MAX_RETRY_AFTER_MS, but never less than the backoff, and all retries of
+ * one call stay within MAX_RETRY_ATTEMPTS and MAX_RETRY_WINDOW_MS.
+ */
+export function planModelCallRetry(error: unknown, state: IAgentRetryState): TAgentRetryDecision {
+  if (plugins.isModelLimitError(error) && error.limit.kind === 'usage_limit') return { action: 'fail', error };
+  const signal = readRetrySignal(error, state.now);
+  if (signal === undefined) return { action: 'not-retryable' };
+  if (state.attempt >= MAX_RETRY_ATTEMPTS) return { action: 'fail', error };
+  const delayMs = Math.max(backoffDelayMs(state.attempt + 1), signal.requestedDelayMs ?? 0);
+  if (delayMs > MAX_RETRY_AFTER_MS || state.retriedMs + delayMs > MAX_RETRY_WINDOW_MS) {
+    return { action: 'fail', error: overdueLimitError(error, signal, state) };
+  }
+  return { action: 'retry', delayMs, reason: signal.reason };
+}

package/ts_agent/smartagent.usage.ts

@@ -0,0 +1,66 @@
+import type { LanguageModelUsage } from './plugins.js';
+import type {
+  IAgentUsage,
+  TAgentModelCallUnreportedReason,
+  TAgentModelCallUsageReporter,
+} from './smartagent.interfaces.js';
+
+/** The identity of the language model whose calls a recorder follows. */
+export interface IAgentModelCallUsageRecorderModel {
+  readonly provider: string;
+  readonly modelId: string;
+}
+
+/**
+ * Follows the calls of one language model and reports each call's usage exactly once.
+ * Call `start()` when a model call begins, `end()` when its provider reports usage, and `settle()`
+ * when the call ends otherwise. A call that is still open when the next one starts ended without
+ * usage and is reported as `unreported` with reason `missing`.
+ */
+export class AgentModelCallUsageRecorder {
+  private open = false;
+
+  constructor(
+    private readonly model: IAgentModelCallUsageRecorderModel,
+    private readonly report: TAgentModelCallUsageReporter,
+  ) {}
+
+  /** A model call begins. */
+  public start(): void {
+    this.settle('missing');
+    this.open = true;
+  }
+
+  /** The provider reported the usage of the current call. A count it leaves out counts as zero. */
+  public end(responseModelId: string, providerUsage: LanguageModelUsage): void {
+    this.open = false;
+    const inputTokens = providerUsage.inputTokens ?? 0;
+    const outputTokens = providerUsage.outputTokens ?? 0;
+    const usage: IAgentUsage = {
+      inputTokens,
+      outputTokens,
+      totalTokens: inputTokens + outputTokens,
+      cacheReadTokens: providerUsage.inputTokenDetails.cacheReadTokens ?? 0,
+      cacheWriteTokens: providerUsage.inputTokenDetails.cacheWriteTokens ?? 0,
+    };
+    this.report({
+      status: 'reported',
+      provider: this.model.provider,
+      requestedModelId: this.model.modelId,
+      responseModelId,
+      usage,
+    });
+  }
+
+  /** The current call ended without usage. Does nothing when no call is open. */
+  public settle(reason: TAgentModelCallUnreportedReason): void {
+    if (!this.open) return;
+    this.open = false;
+    this.report({
+      status: 'unreported',
+      provider: this.model.provider,
+      requestedModelId: this.model.modelId,
+      reason,
+    });
+  }
+}