やり直せる操作とやり直せない操作を分けて任せる — 可逆性で自律度を決めるエージェント設計

// reversibility.ts — 操作を可逆性で3階層に分類する
export type Tier = "auto" | "checkpoint" | "irreversible";
 
export interface AgentOperation {
  kind: string;        // 例: "file.edit", "remoteConfig.publish"
  target: string;      // 例: "src/App.tsx", "production"
  reversalCostSec?: number; // 戻すのに必要な秒数の見積もり（任意）
}
 
// 不可逆操作は「許可リスト」ではなく「明示列挙」で管理する。
// 列挙漏れがあった場合は安全側（irreversible）に倒す。
const IRREVERSIBLE_KINDS = new Set([
  "appstore.submit",
  "playstore.release",
  "db.migrate",
  "remoteConfig.publish",
  "billing.charge",
  "notification.send",
  "email.send",
]);
 
const AUTO_KINDS = new Set([
  "file.edit",
  "file.create",
  "test.run",
  "build.local",
  "draft.generate",
]);
 
export function classify(op: AgentOperation): Tier {
  // 1. 本番対象の操作は、種別が安全でも一段引き上げる
  const hitsProduction = op.target === "production" || op.target.startsWith("prod");
 
  if (IRREVERSIBLE_KINDS.has(op.kind)) return "irreversible";
  if (hitsProduction) return "irreversible"; // 本番に触れるなら不可逆扱い
  if (AUTO_KINDS.has(op.kind)) return "auto";
 
  // 2. 戻すコストが大きい操作はチェックポイントを要求する
  if ((op.reversalCostSec ?? 0) > 30) return "checkpoint";
 
  // 3. 判定不能なものは安全側に倒す（=チェックポイントは最低限残す）
  return "checkpoint";
}

// guard.ts — 階層ごとに実行のしかたを切り替える
import { classify, AgentOperation } from "./reversibility";
import { snapshot, requireApproval } from "./checkpoint";
 
export interface ExecResult {
  executed: boolean;
  checkpointId?: string;
  reason?: string;
}
 
export async function guardedExecute(
  op: AgentOperation,
  run: () => Promise<void>,
): Promise<ExecResult> {
  const tier = classify(op);
 
  if (tier === "auto") {
    await run();
    return { executed: true };
  }
 
  if (tier === "checkpoint") {
    // 戻せる点を残してから実行する。スナップショットに失敗したら実行しない。
    const checkpointId = await snapshot(op);
    if (!checkpointId) {
      return { executed: false, reason: "snapshot-failed" };
    }
    await run();
    return { executed: true, checkpointId };
  }
 
  // irreversible: 人間が中身を見て通すまで実行しない
  const approved = await requireApproval(op);
  if (!approved) {
    return { executed: false, reason: "rejected-by-human" };
  }
  await run();
  return { executed: true };
}

// checkpoint.ts — 操作の種別に応じた巻き戻し点を作る
import { execFile } from "node:child_process";
import { promisify } from "node:util";
const sh = promisify(execFile);
 
export async function snapshot(op: { kind: string; target: string }): Promise<string | null> {
  const id = `cp-${Date.now()}`;
  try {
    if (op.kind.startsWith("file.") || op.kind.startsWith("build.")) {
      // git stash で作業ツリーごと退避し、いつでも戻せるようにする
      await sh("git", ["stash", "push", "-u", "-m", id]);
      return id;
    }
    if (op.kind.startsWith("config.")) {
      // 設定ファイルはタイムスタンプ付きでコピーしておく
      await sh("cp", [op.target, `${op.target}.${id}.bak`]);
      return id;
    }
    // それ以外は巻き戻し点を作れない可能性がある。null を返して実行を止める。
    return null;
  } catch {
    return null;
  }
}
 
export async function rollback(checkpointId: string): Promise<void> {
  // git stash の一覧から該当 ID を探して戻す
  const { stdout } = await sh("git", ["stash", "list"]);
  const line = stdout.split("\n").find((l) => l.includes(checkpointId));
  if (line) {
    const ref = line.split(":")[0]; // 例: stash@{0}
    await sh("git", ["stash", "pop", ref]);
  }
}

// approval.ts — 不可逆操作の直前に最小限の情報だけ提示する
export interface ApprovalCard {
  whatChanges: string;   // 何が変わるか（1行）
  whoIsAffected: string; // 誰に影響するか
  ifWrong: string;       // 間違っていたらどうなるか
}
 
export function buildCard(op: { kind: string; target: string }): ApprovalCard {
  if (op.kind === "remoteConfig.publish") {
    return {
      whatChanges: `Remote Config「${op.target}」を本番に反映`,
      whoIsAffected: "次回起動する全ユーザー（取り消し後も配信済み端末は戻らない）",
      ifWrong: "誤った値が端末にキャッシュされ、強制更新まで残る",
    };
  }
  if (op.kind === "appstore.submit") {
    return {
      whatChanges: `App Store へ「${op.target}」を申請`,
      whoIsAffected: "審査チーム・既存ユーザー",
      ifWrong: "審査リジェクトまたは不本意なバージョン公開、取り下げに数日",
    };
  }
  return {
    whatChanges: `${op.kind} を ${op.target} に実行`,
    whoIsAffected: "外部システム",
    ifWrong: "手動での巻き戻しが必要",
  };
}