dynamic sub-agents が枝分かれしすぎる前に — 深さ予算とファンアウト上限の設計

type SpawnContext = {
  depth: number;       // 現在の深さ(ルートは 0)
  maxDepth: number;    // 深さ予算
  traceId: string;     // 木全体を追跡するための ID
};
 
// サブエージェント起動の薄いラッパ
async function runSubAgent(
  prompt: string,
  ctx: SpawnContext,
  spawnChildren: (childCtx: SpawnContext) => Promise<void>,
) {
  // 深さ上限に達したら、子を立てずに単独で完結させる指示を足す
  const canSpawn = ctx.depth < ctx.maxDepth;
  const guardedPrompt = canSpawn
    ? prompt
    : `${prompt}\n\n[制約] これ以上サブエージェントを起動しないこと。` +
      `この作業はあなた自身で完結させてください。`;
 
  const result = await antigravity.agents.run({
    prompt: guardedPrompt,
    metadata: { traceId: ctx.traceId, depth: ctx.depth },
  });
 
  if (canSpawn) {
    // 子を立てるときは必ず depth+1 を渡す
    await spawnChildren({ ...ctx, depth: ctx.depth + 1 });
  }
  return result;
}

class FanOutLimiter {
  private running = 0;
  private queue: (() => void)[] = [];
 
  constructor(private readonly maxConcurrent: number) {}
 
  async acquire(): Promise<void> {
    if (this.running < this.maxConcurrent) {
      this.running++;
      return;
    }
    // 空きが出るまで待つ
    await new Promise<void>((resolve) => this.queue.push(resolve));
    this.running++;
  }
 
  release(): void {
    this.running--;
    const next = this.queue.shift();
    if (next) next();
  }
 
  get inFlight(): number {
    return this.running;
  }
}
 
// 木全体で1つのリミッタを共有する
const limiter = new FanOutLimiter(6);
 
async function runGuarded(prompt: string, ctx: SpawnContext) {
  await limiter.acquire();
  try {
    return await runSubAgent(prompt, ctx, async (childCtx) => {
      // 子の起動も同じリミッタを通す
      await runGuarded(childPrompt, childCtx);
    });
  } finally {
    limiter.release();
  }
}

type SpawnContext = {
  depth: number;
  maxDepth: number;
  traceId: string;
  signal: AbortSignal;  // 木全体で共有する停止シグナル
};
 
async function runSubAgent(prompt: string, ctx: SpawnContext, spawn) {
  // すでにキャンセル済みなら即座に降りる
  if (ctx.signal.aborted) return { skipped: true };
 
  const result = await antigravity.agents.run({
    prompt,
    signal: ctx.signal,           // SDK に停止シグナルを渡す
    metadata: { traceId: ctx.traceId, depth: ctx.depth },
  });
  return result;
}
 
// ルートで木を起動する
const controller = new AbortController();
 
// 木全体の上限時間(例: 20分)を超えたら全枝を止める
const deadline = setTimeout(() => controller.abort("deadline"), 20 * 60 * 1000);
 
try {
  await runGuarded(rootPrompt, {
    depth: 0,
    maxDepth: 2,
    traceId: crypto.randomUUID(),
    signal: controller.signal,
  });
} finally {
  clearTimeout(deadline);
}