エージェントが壊す前提で組む — ブラスト半径を小さく保つ運用設計

// scope-guard.ts — 許可された範囲外の副作用を実行時に拒否する
import path from "node:path";
 
export class ScopeGuard {
  constructor(private allowGlobs: string[], private root: string) {}
 
  private isAllowed(target: string): boolean {
    const rel = path.relative(this.root, path.resolve(this.root, target));
    if (rel.startsWith("..")) return false; // ルート外は即拒否
    return this.allowGlobs.some((g) => this.match(rel, g));
  }
 
  assertWritable(target: string) {
    if (!this.isAllowed(target)) {
      throw new ScopeViolation(`書き込み拒否: ${target} は許可スコープ外です`);
    }
  }
 
  private match(rel: string, glob: string): boolean {
    const re = new RegExp("^" + glob.replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*") + "$");
    return re.test(rel);
  }
}
 
export class ScopeViolation extends Error {}
 
// 多言語リソースだけ触らせたい作業の例
const guard = new ScopeGuard(["locales/**/*.json"], process.cwd());
guard.assertWritable("locales/ja/common.json"); // OK
// guard.assertWritable("src/payment/stripe.ts"); // throw ScopeViolation

// circuit-breaker.ts — 連続失敗で実行を遮断する
type State = "closed" | "open" | "half-open";
 
export class CircuitBreaker {
  private failures = 0;
  private state: State = "closed";
  private openedAt = 0;
 
  constructor(
    private threshold = 3,        // 連続3回失敗で開放
    private cooldownMs = 10 * 60_000, // 10分間は実行を止める
  ) {}
 
  async run<T>(task: () => Promise<T>): Promise<T> {
    if (this.state === "open") {
      if (Date.now() - this.openedAt < this.cooldownMs) {
        throw new CircuitOpen("回路開放中: クールダウンを待機します");
      }
      this.state = "half-open"; // 試しに1回だけ通す
    }
    try {
      const result = await task();
      this.reset();
      return result;
    } catch (err) {
      this.recordFailure();
      throw err;
    }
  }
 
  private recordFailure() {
    this.failures += 1;
    if (this.failures >= this.threshold) {
      this.state = "open";
      this.openedAt = Date.now();
    }
  }
  private reset() { this.failures = 0; this.state = "closed"; }
}
 
export class CircuitOpen extends Error {}

// dead-letter.ts — 失敗タスクを退避し、選別して再投入する
interface FailedTask {
  id: string;
  payload: unknown;
  error: string;
  attempts: number;
  firstFailedAt: number;
}
 
export class DeadLetterQueue {
  private queue: FailedTask[] = [];
 
  park(id: string, payload: unknown, error: Error, attempts: number) {
    this.queue.push({ id, payload, error: error.message, attempts, firstFailedAt: Date.now() });
  }
 
  // 再投入条件: 試行5回未満 かつ 同型エラーでない ものだけ戻す
  drain(isRetryable: (t: FailedTask) => boolean): FailedTask[] {
    const retryable = this.queue.filter((t) => t.attempts < 5 && isRetryable(t));
    this.queue = this.queue.filter((t) => !retryable.includes(t));
    return retryable;
  }
 
  report() {
    const byError = new Map<string, number>();
    for (const t of this.queue) byError.set(t.error, (byError.get(t.error) ?? 0) + 1);
    return [...byError.entries()].sort((a, b) => b[1] - a[1]); // 多い順
  }
}