本番に触れる前にエージェントの操作を空振りさせる — 副作用ゼロのドライラン層をどう設計するか

// boundary.ts — 副作用境界の本体
import { Effect } from "./effect";
 
export type RunMode = "dry-run" | "commit";
 
export class SideEffectBoundary {
  private planned: Effect[] = [];
 
  constructor(private mode: RunMode) {}
 
  // エージェントのツールは副作用を直接実行せず、必ずこれを呼ぶ
  async apply(effect: Effect): Promise<void> {
    if (this.mode === "dry-run") {
      // 実行はしない。計画として積むだけ
      this.planned.push(effect);
      return;
    }
    // 本番モード: 記録してから実行する（実行前に痕跡を残す）
    this.planned.push(effect);
    await effect.commit();
  }
 
  // 削除は危険度が高いので、件数の急増を検知できるようにしておく
  get deleteCount(): number {
    return this.planned.filter((e) => e.kind === "delete").length;
  }
 
  get plan(): readonly Effect[] {
    return this.planned;
  }
}

// tools/remote-config.ts — ツールから副作用を申告する例
import { SideEffectBoundary } from "../boundary";
 
export async function setCampaignFlag(
  boundary: SideEffectBoundary,
  key: string,
  value: boolean,
  client: RemoteConfigClient,
): Promise<void> {
  const before = await client.get(key); // 読み取りは副作用ではないので常に実行
  await boundary.apply({
    kind: "kv-write",
    summary: `Remote Config ${key} を ${before} から ${value} へ変更`,
    target: `remote-config/${key}`,
    before,
    after: value,
    commit: async () => {
      await client.set(key, value);
    },
  });
}

// render.ts — 計画を人間が読める差分テキストに整形する
import { Effect } from "./effect";
 
export function renderPlan(plan: readonly Effect[]): string {
  if (plan.length === 0) return "(変更なし)";
 
  const lines: string[] = [];
  const deletes = plan.filter((e) => e.kind === "delete").length;
  lines.push(`計画された変更: ${plan.length}件（うち削除 ${deletes}件）`);
  lines.push("");
 
  for (const e of plan) {
    const mark = e.kind === "delete" ? "[削除]" : "[変更]";
    lines.push(`${mark} ${e.target}`);
    lines.push(`    ${e.summary}`);
    if (e.kind !== "delete" && e.before !== undefined) {
      lines.push(`    before: ${JSON.stringify(e.before)}`);
      lines.push(`    after:  ${JSON.stringify(e.after)}`);
    }
  }
  return lines.join("\n");
}

// run.ts — 二相実行: まずドライラン、承認後に同じ計画を commit
import { SideEffectBoundary } from "./boundary";
import { renderPlan } from "./render";
 
export async function runWithRehearsal(
  agentTask: (b: SideEffectBoundary) => Promise<void>,
  approve: (planText: string, deletes: number) => Promise<boolean>,
): Promise<{ applied: boolean; planText: string }> {
  // 第1相: ドライラン。副作用ゼロで計画だけを作る
  const dry = new SideEffectBoundary("dry-run");
  await agentTask(dry);
  const planText = renderPlan(dry.plan);
 
  // 計画を人間（またはルール）が承認するか判定
  const ok = await approve(planText, dry.deleteCount);
  if (!ok) {
    return { applied: false, planText };
  }
 
  // 第2相: 承認された計画をそのまま実行する
  // 注意: agentTask を再実行せず、第1相で得た Effect を commit する
  const commit = new SideEffectBoundary("commit");
  for (const effect of dry.plan) {
    await commit.apply(effect);
  }
  return { applied: true, planText };
}

// effect.ts に precondition を追加
export interface Effect {
  kind: EffectKind;
  summary: string;
  target: string;
  before?: unknown;
  after?: unknown;
  // commit 直前に呼ばれる。false を返したら世界が変わっているので中断する
  precondition?: () => Promise<boolean>;
  commit: () => Promise<void>;
}

// boundary.ts の commit 時に前提条件を検証する
async apply(effect: Effect): Promise<void> {
  if (this.mode === "dry-run") {
    this.planned.push(effect);
    return;
  }
  if (effect.precondition) {
    const stillValid = await effect.precondition();
    if (!stillValid) {
      throw new StalePlanError(
        `計画が古くなっています: ${effect.target} の前提が変わりました`,
      );
    }
  }
  this.planned.push(effect);
  await effect.commit();
}