[GL-18] Agent Orchestrator (the Agent OS Core)

[benevolentbandwidth-nurtekin]

Stream E — Orchestrator

Labels: core, orchestrator
Depends on: GL-6, GL-11, GL-12, GL-13, GL-14, GL-15, GL-16, GL-17
Effort: 8–10 hours

Assign your two most capable contributors to this issue.

Summary

The brain of the system. Aware of every stage. Routes between agents. Enforces the rule that LLMs and agents never communicate directly — all LLM calls flow through the Gateway, all agent invocations flow through the Orchestrator.

Pipeline Inside process()

1. Run InputSanitizer. Unsafe → localized safe fallback. Flagged → log and continue.
2. Run LocationDetector.detect(). Set message.location.
3. Run IntentClassifier.classify(). Determine submission_type and stage.
4. Resolve current agent via AgentRegistry.find_best_agent(stage, language).
5. Invoke agent. Agents are stateless functions, not objects with state. They receive message + session + registry refs and return CanonicalResponse.
6. Emit appropriate LogEvent to session.log_buffer.
7. Advance session stage if agent signals completion.
8. Return response to worker for delivery.

Stage Transition Map (enforced here, not in agents)

intake → awaiting_evidence (identification agent completes)
awaiting_evidence → pending_score (verification agent emits score)
pending_score → scored (GiveLight confirms — one-way door)

Invalid transitions raise InvalidStageTransitionError.

Human Escalation Path

When verification agent returns recommendation = human_escalate: emit HUMAN_ESCALATION log event with full context. Tell user: 'Your submission has been forwarded to our review team. You will hear from GiveLight directly.' Advance stage to pending_score.

Architecture Rule

Agents do not hold references to LLM adapters. The orchestrator passes a gateway reference to each agent invocation. The agent calls gateway.call(). This chain is structural — enforced in code review.

Acceptance Criteria

• Full pipeline executes for intake message end-to-end.
• Full pipeline executes for evidence submission.
• Stage transitions validated — error on illegal jump.
• human_escalate sends correct user message and emits event.
• Agents never hold direct adapter references.
• LogEvent emitted for every stage transition.
• Integration test: intake through verification score, end-to-end.