research_team.007

-- SPDX-License-Identifier: MPL-2.0
-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
--
-- Example: A research team of agents that investigate a topic.
-- Demonstrates all six pillars of 007.

-- ============================================================
-- 1. DATA CONTEXT — what agents know (Harvard: cannot execute)
-- ============================================================

@total data research_config = {
  max_sources: 5 + 0,
  confidence_threshold: 0.8 + 0.0,
  model: "claude-sonnet-4-6"
}

-- ============================================================
-- 2. LOCALES — where computation runs
-- ============================================================

locale api = Remote(url: "https://api.anthropic.com")
locale local_machine = Local

-- ============================================================
-- 3. PROTOCOLS — typed communication contracts
-- ============================================================

session protocol Investigation {
  Requester -> Lead: Query(topic: String)

  loop gather {
    Lead -> Searcher: SearchTask(query: String)

    branch by Searcher {
      | success given { has_findings: true } -> {
          Searcher -> Lead: Results(findings: Data)
      }
      | failure given { has_findings: false } -> {
          Searcher -> Lead: Failed(reason: String)
      }
    }
  }

  Lead -> Analyst: Synthesise(all_findings: Data)
  Analyst -> Lead: Analysis(conclusion: Data, confidence: Float)

  branch by Lead {
    | confident given { above_threshold: true } -> {
        Lead -> Requester: Report(conclusion: Data)
    }
    | uncertain given { above_threshold: false } -> {
        Lead -> Requester: Inconclusive(partial: Data, gaps: String)
    }
  }
}

-- ============================================================
-- 4. AGENTS — with capabilities and linear handles
-- ============================================================

agent Searcher(caps: Cap[web_fetch, read_file])
  implements Investigation.Searcher
  on locale local_machine
{
  @total data searcher_config = {
    sources_checked: 0 + 0
  }

  control {
    on receive(task: SearchTask) {
      let results = web_search(task.query)
      if results.length > 0 {
        send(lead, Results(results))
      } else {
        send(lead, Failed("No results found"))
      }
    }
  }
}

agent Analyst(caps: Cap[call_api, reason])
  implements Investigation.Analyst
  on locale api
{
  control {
    on receive(task: Synthesise) {
      let conclusion = reason(task.all_findings)
      let confidence = assess_confidence(conclusion)
      send(lead, Analysis(conclusion, confidence))
    }
  }
}

agent Lead(caps: Cap[spawn, coordinate, web_fetch, read_file, call_api, reason])
  implements Investigation.Lead
{
  control {
    on receive(query: Query) {
      -- Spawn workers with SUBSET of Lead's capabilities
      -- Linear handles: must be consumed
      linear let searcher = spawn Searcher(
        caps: [web_fetch, read_file]
      )
      linear let analyst = spawn Analyst(
        caps: [call_api, reason]
      )

      -- Gather evidence (protocol loop)
      loop gather {
        linear let (searcher2, results) = exchange(
          searcher, SearchTask(query.topic)
        )
        match results {
          | Results(findings) -> {
              send(self, findings)
          }
          | Failed(reason) -> {
              log("Search failed: " ++ reason)
          }
        }
      }

      -- Synthesise
      linear let (analyst2, analysis) = exchange(
        analyst, Synthesise(all_findings)
      )

      -- Decide and report
      if analysis.confidence >= research_config.confidence_threshold {
        send(requester, Report(analysis.conclusion))
      } else {
        send(requester, Inconclusive(analysis.conclusion, identify_gaps(all_findings)))
      }

      -- Consume remaining handles (protocol complete)
      send_final(searcher2, Shutdown)
      send_final(analyst2, Shutdown)
    }
  }
}

-- ============================================================
-- 5. SUPERVISOR — fault tolerance
-- ============================================================

supervisor ResearchTeam {
  strategy: one_for_one
  max_restarts: 3 per 60 s

  children: [
    agent Lead(caps: [spawn, coordinate, web_fetch, read_file, call_api, reason]),
  ]

  on child_crash(child: String, crash_reason: String) {
    match crash_reason {
      | Transient -> restart(child)
      | Fatal     -> raise_escalation(crash_reason)
    }
  }
}

-- ============================================================
-- 6. CHOREOGRAPHY — global view of the multi-agent dance
-- ============================================================

choreography investigate(
  requester: Requester,
  lead: Lead,
  searchers: [Searcher],
  analyst: Analyst
) {
  requester -> lead: assign(topic)

  parallel for searcher in searchers {
    lead -> searcher: assign_task(subtask)
    searcher -> lead: report(findings)
  }

  lead -> analyst: synthesise(all_findings)
  analyst -> lead: conclude(analysis)
  lead -> requester: deliver(report)
}