Antigravity の Retry を本番品質で設計する — 冪等性・バックオフ・コスト上限・失敗トリアージ

// src/retry/backoff.ts
// 指数バックオフ + ジッター + 最大試行回数 + 最大待ち時間の組み合わせ。
// これを「再試行してよい」と判断したエラーにだけ適用する。
 
export type RetryOptions = {
  maxAttempts: number;
  baseDelayMs: number;
  maxDelayMs: number;
  shouldRetry: (err: unknown, attempt: number) => boolean;
  onRetry?: (err: unknown, attempt: number, delayMs: number) => void;
};
 
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
export async function retryWithBackoff<T>(
  fn: () => Promise<T>,
  opts: RetryOptions,
): Promise<T> {
  let lastError: unknown;
  for (let attempt = 1; attempt <= opts.maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      lastError = err;
      if (attempt === opts.maxAttempts || !opts.shouldRetry(err, attempt)) {
        throw err;
      }
      // full jitter: 0 〜 base*2^attempt の範囲でランダム化
      const expo = Math.min(opts.baseDelayMs * 2 ** attempt, opts.maxDelayMs);
      const delay = Math.floor(Math.random() * expo);
      opts.onRetry?.(err, attempt, delay);
      await sleep(delay);
    }
  }
  throw lastError;
}
 
// 使い方
await retryWithBackoff(
  () => fetch("https://api.example.com/data").then((r) => r.json()),
  {
    maxAttempts: 5,
    baseDelayMs: 500,
    maxDelayMs: 30_000,
    shouldRetry: (err) => {
      // 後述する「失敗トリアージ」でここを埋める
      return isTransientError(err);
    },
    onRetry: (err, attempt, delay) => {
      console.log(`retry attempt=${attempt} delay=${delay}ms error=${String(err)}`);
    },
  },
);

// src/retry/budget.ts
// タスク単位のコスト上限をエージェント実行ループに組み込む。
// LLM レスポンスから usage を取り出し、合計が超えたら BudgetExceeded を投げる。
 
export class BudgetExceeded extends Error {
  constructor(
    public readonly used: number,
    public readonly budget: number,
  ) {
    super(`budget exceeded: used=${used} budget=${budget}`);
  }
}
 
export class TokenBudget {
  private used = 0;
 
  constructor(
    private readonly budget: number,
    private readonly onWarn?: (used: number, budget: number) => void,
  ) {}
 
  track(usage: { prompt_tokens: number; completion_tokens: number }) {
    this.used += usage.prompt_tokens + usage.completion_tokens;
    if (this.used > this.budget) {
      throw new BudgetExceeded(this.used, this.budget);
    }
    // 80% 超えで警告（Slack 通知・メトリクス発火などに繋げる）
    if (this.used > this.budget * 0.8) {
      this.onWarn?.(this.used, this.budget);
    }
  }
 
  remaining(): number {
    return Math.max(0, this.budget - this.used);
  }
}
 
// 使い方（エージェント実行ループの内側）
const budget = new TokenBudget(200_000, (used, total) => {
  console.warn(`budget at 80%: ${used}/${total}`);
});
 
for (const step of plannedSteps) {
  try {
    const response = await callLLM(step.prompt);
    budget.track(response.usage);
    applyResult(response);
  } catch (err) {
    if (err instanceof BudgetExceeded) {
      await notifyHuman("budget exceeded, human review required", { err });
      await saveCheckpoint(step);
      throw err; // ループ全体を止める
    }
    throw err;
  }
}

// src/retry/triage.ts
// エラーを transient / permanent / ambiguous に分類するトリアージ関数。
// このロジックは実運用で必ず育てる。新種エラーが来るたびに分類を追加する。
 
export type ErrorClass = "transient" | "permanent" | "ambiguous";
 
export function classifyError(err: unknown): ErrorClass {
  if (!(err instanceof Error)) return "ambiguous";
  const msg = err.message.toLowerCase();
 
  // --- 認証・権限・入力エラーは再試行しない ---
  if (/unauthorized|forbidden|invalid_api_key|authentication/.test(msg)) {
    return "permanent";
  }
  if (/validation|invalid request|bad request|schema/.test(msg)) {
    return "permanent";
  }
  if (/model_not_found|unknown model/.test(msg)) {
    return "permanent";
  }
 
  // --- 一時的なネットワーク・レートリミットは再試行する ---
  if (/rate.?limit|too many requests|429/.test(msg)) {
    return "transient";
  }
  if (/timeout|econnreset|etimedout|network/.test(msg)) {
    return "transient";
  }
  if (/503|service unavailable|overloaded/.test(msg)) {
    return "transient";
  }
 
  // --- 曖昧なものは一度だけ再試行する ---
  if (/500|internal server|json|parse/.test(msg)) {
    return "ambiguous";
  }
 
  return "ambiguous";
}
 
// 使い方: retry ループの shouldRetry に組み込む
export function shouldRetryFromTriage(err: unknown, attempt: number): boolean {
  const klass = classifyError(err);
  if (klass === "permanent") return false;
  if (klass === "transient") return attempt < 5;
  if (klass === "ambiguous") return attempt < 2; // 一度だけ
  return false;
}

// src/retry/checkpoint.ts
// チェックポイントと Retry を組み合わせた「再開可能なエージェント」の最小実装。
// 保存先は JSON ファイル / KV / Firestore など、耐久性のあるストレージを使うこと。
 
import fs from "node:fs/promises";
 
type Step = { id: string; run: () => Promise<void> };
 
type Checkpoint = {
  completed: string[];
  updatedAt: string;
};
 
export async function runResumable(
  steps: Step[],
  checkpointPath: string,
): Promise<void> {
  let cp: Checkpoint;
  try {
    cp = JSON.parse(await fs.readFile(checkpointPath, "utf-8"));
  } catch {
    cp = { completed: [], updatedAt: new Date().toISOString() };
  }
 
  for (const step of steps) {
    if (cp.completed.includes(step.id)) {
      console.log(`skip already-completed step: ${step.id}`);
      continue;
    }
    try {
      await step.run();
      cp.completed.push(step.id);
      cp.updatedAt = new Date().toISOString();
      await fs.writeFile(checkpointPath, JSON.stringify(cp, null, 2));
    } catch (err) {
      // 失敗時もチェックポイントを保存し、次回はここから再開できるようにする
      await fs.writeFile(checkpointPath, JSON.stringify(cp, null, 2));
      throw err;
    }
  }
}