The Orchestrator.
How to Build an AI
That Reads Ten Others
and Finds Where They
Actually Disagree.

interface TensionMap {

  // Required — validated on every orchestrator response
  version: string;          // schema version for backwards compat
  queryId: string;          // correlates with agent call logs
  generatedAt: number;      // unix timestamp
  round: 1 | 2;            // which synthesis pass produced this

  // Consensus zones — where agents meaningfully agree
  consensus: {
    claim: string;            // the agreed-upon assertion
    supportingAgents: string[];  // which agents hold this view
    confidence: 0..1;           // orchestrator's confidence in the consensus
    loadBearing: boolean;       // does this affect the conclusion?
  }[];

  // Tension entries — the core value of the system
  tensions: {
    id: string;                // unique — used in Round 2 targeting
    agentA: string;            // first agent in conflict
    agentB: string;            // second agent in conflict
    claimA: string;            // agentA's specific position
    claimB: string;            // agentB's specific position
    type: 'factual'|'interpretive'|'emphasis'; // clash type
    severity: 1..10;            // 6+ triggers Round 2
    loadBearing: boolean;      // affects conclusion?
    resolvable: boolean;       // can more info resolve it?
    recommendation: string;    // how should the human weigh this?
  }[];

  // Synthesis — the orchestrator's reading of the full landscape
  synthesis: {
    headline: string;          // one-sentence summary of state of play
    majorFindings: string[];   // top 3-5 substantive conclusions
    openQuestions: string[];   // unresolved after Round 2 (if applicable)
    confidenceProfile: {        // not a single score — per-domain confidence
      [agentId: string]: 0..1
    };
  };

  // Round 2 targeting — populated before R2 call, nulled after
  round2Target?: {
    tensionId: string;          // which tension to resolve
    agents: [string, string];   // only these two agents are re-queried
    prompt: string;            // the specific clash framed as a question
  };
}

interface ClashScore {
  agentPair: [string, string];
  severity: number;      // 1-10
  type: 'factual' | 'interpretive' | 'emphasis';
  loadBearing: boolean;
}

async function detectClashes(
  responses: AgentResponse[],
  env: Env
): Promise<ClashScore[]> {

  // Phase 1: Extract all claims from each response
  // The orchestrator reads each response and identifies
  // load-bearing assertions (claims that affect the conclusion)
  const claims = await extractClaims(responses, env);

  // Phase 2: Compare claims across agent pairs
  // Only compare load-bearing claims — peripheral diffs are noise
  const clashes: ClashScore[] = [];

  for (let i = 0; i < responses.length; i++) {
    for (let j = i + 1; j < responses.length; j++) {

      const pairClash = await scorePairClash({
        agentA: responses[i].agentId,
        agentB: responses[j].agentId,
        claimsA: claims[i].loadBearing,
        claimsB: claims[j].loadBearing,
      }, env);

      // Severity scoring by type:
      // Factual contradiction:    8-10 (direct truth claim conflict)
      // Interpretive divergence:  4-7  (same facts, different meaning)
      // Emphasis difference:      1-3  (same view, different priority)
      if (pairClash.severity > 0) clashes.push(pairClash);
    }
  }

  return clashes.sort((a, b) => b.severity - a.severity);
}

function shouldTriggerRound2(clashes: ClashScore[]): boolean {
  // Round 2 condition: 2+ load-bearing clashes scoring ≥ 6/10
  const highSeverity = clashes.filter(c =>
    c.severity >= 6 && c.loadBearing && c.type !== 'emphasis'
  );
  return highSeverity.length >= 2;
}

// If Round 2 triggers, only the two conflicting agents are re-queried
// Not all ten — targeted, not expensive
function buildRound2Prompt(clash: ClashScore, responses: AgentResponse[]): string {
  const [a, b] = clash.agentPair;
  return `
    ${responses[a].agentId} argued: "${clash.claimA}"
    ${responses[b].agentId} argued: "${clash.claimB}"

    These claims are in direct conflict on a load-bearing point.
    Address the opposing argument specifically.
    Do not restate your original position without engaging the challenge.
  `;
}

const ORCHESTRATOR_SYSTEM_PROMPT = `
You are the Consilium Orchestrator. You receive responses from 10 domain
expert AI agents and produce a structured tension map.

YOUR CARDINAL RULES:

1. PRESERVE DISAGREEMENT. Do not synthesize away genuine conflict.
   If two agents disagree on a load-bearing claim, that conflict must
   appear in the tensions array regardless of how uncomfortable it is.

2. CLASSIFY BEFORE SCORING. Every disagreement is one of:
   - factual: directly contradictory truth claims (score 8-10)
   - interpretive: same facts, different meaning (score 4-7)
   - emphasis: same view, different priority (score 1-3)

3. STRUCTURED OUTPUT REQUIRED. Your entire response must be valid JSON
   matching the TensionMap schema. No prose, no preamble, no markdown.
   A response without a tensions array will be treated as invalid.

4. CONFIDENCE IS PER-DOMAIN. Do not produce a single confidence score.
   Rate each agent's domain contribution independently.

5. ROUND 2 ONLY FOR LOAD-BEARING FACTUAL CLASHES. Emphasis
   differences do not trigger Round 2. Cost is real.

WHAT A GOOD SYNTHESIS LOOKS LIKE:
- tensions array has 3-8 entries for a complex query
- At least one consensus entry per major topic area
- openQuestions lists what Round 2 did NOT resolve (honesty)
- headline is one sentence, no hedging, no "it depends"

WHAT A BAD SYNTHESIS LOOKS LIKE:
- Empty or single-item tensions array on a complex topic
- Headline that begins with "It depends" or "Both perspectives..."
- Confidence scores all above 0.85 on contested empirical claims
- openQuestions is empty after a contested Round 2
`;

async function streamOrchestratedResponse(message: string, env: Env) {
  const { readable, writable } = new TransformStream();
  const writer = writable.getWriter();
  const enc = new TextEncoder();
  const emit = (event: string, data: any) =>
    writer.write(enc.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));

  // PHASE 1: Fan out to all 10 agents, stream summaries as they arrive
  // User sees content within ~300ms — not blank screen for 10 seconds
  const agentPromises = AGENTS.map(id =>
    callAgent(id, message, env).then(response => {
      emit('agent_complete', { agentId: id, summary: response.summary });
      return response;
    })
  );

  // Wait for all 10 — allSettled so one failure doesn't block synthesis
  const settled = await Promise.allSettled(agentPromises);
  const responses = settled
    .filter(r => r.status === 'fulfilled')
    .map(r => (r as any).value);

  // PHASE 2: Clash detection + synthesis — begins after all 10 complete
  await emit('orchestrating', { message: 'Mapping tensions...', agentCount: responses.length });

  const clashes = await detectClashes(responses, env);
  let finalResponses = responses;

  if (shouldTriggerRound2(clashes)) {
    await emit('round2_triggered', { clashes: clashes.filter(c => c.severity >= 6) });
    finalResponses = await runRound2(responses, clashes, env);
  }

  // Stream the tension map as it generates (SSE from Claude)
  const tensionMap = await synthesize(finalResponses, env, (chunk: string) => {
    writer.write(enc.encode(`event: synthesis_chunk\ndata: ${chunk}\n\n`));
  });

  // Final emit: validated tension map JSON
  if (!validateTensionMap(tensionMap)) {
    await emit('error', { code: 'INVALID_TENSION_MAP', retry: true });
  } else {
    await emit('tension_map', tensionMap);
  }

  writer.close();
  return new Response(readable, {
    headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' }
  });
}