Skip to content

DECISIONS.md

Latest commit

 

History

History
78 lines (66 loc) · 3.91 KB

DECISIONS.md

File metadata and controls

78 lines (66 loc) · 3.91 KB
Raw

ORCA — Kickoff Decisions

ORCA = Orchestration & Risk Control for Agents. Resolved before build start, based on the tech spec (Interlock_Tech_Specv3) review. If you change one of these, tell the whole team — other people's code depends on them.

1. Enforcement works on wrapped tools, not just our harness

The LangGraph adapter must wrap the tools themselves, so every tool call passes through the Policy Gate before it runs — same as agents built on our own harness. Observing/logging alone is not enough; the cross-framework enforcement claim depends on this. (Owner: Person A)

2. Approval flow semantics (human-in-the-loop)

  • Waiting: an agent that hits an escalate verdict freezes and stays frozen until a human acts. No timeout, no auto-continue.
  • Denied: the human chooses one of two options in the modal: "Give up" (agent ends the task, emits a failed/closed event) or "Try another way" (agent replans without the blocked action).
  • Approved: the agent simply resumes and executes the approved action. (Owners: Person A for pause/resume in the harness, Person C for the modal's two-option deny UI)

3. Taint propagation — deferred

Cross-agent taint spread (Doc agent reads poisoned file → downstream agents inherit "untrusted") is parked until the end. The schema keeps the data_provenance.tainted field so it can be added without a schema change. Until then, the poisoned-doc demo can set the flag directly on the affected agent's events.

4. Judge agent: live LLM with a mock fallback

Renamed Quality Gate (was "Governance Gate") per the final workflow diagram, July 9. JUDGE_PROVIDER=mock (default) is the deterministic rubric judge — demo-safe, zero network; JUDGE_PROVIDER=llm + LLM_ENDPOINT/LLM_API_KEY/LLM_DEPLOYMENT switches to a strict-prompted second LLM. Beat 2's disagreement (150 vs 1500 PSI) fires on cue either way.

Flag routing (team decision, July 9): a judge disagreement FREEZES the run — the flagged output goes to the same human-review inbox as safety escalations, and nothing downstream proceeds until a human approves / rejects it. It only runs where a step declares a rubric (that's the "optional" in the diagram).

5. One agent at a time → single hash chain is safe

Agents run sequentially, never concurrently. One global hash chain over all events, computed by the single event store writer. If we ever go concurrent, revisit (per-trace chains).

6. Name: ORCA — Orchestration & Risk Control for Agents

(Was "Interlock" in the spec — renamed; "Interlock" alone collides with a known ransomware gang. Keep the safety-interlock metaphor in the pitch, just not as the product name.)

7. Demo beats

Four beats is the goal, not a commitment. Priority if time is short: Beat 3 (attack + block) > Beat 4 (audit/hash-chain) > Beat 1 (cascade) > Beat 2 (judge disagreement). Rehearse with a timer.

8. Secrets

The LLM API key lives in backend_starter/.env (gitignored) on each machine. Never commit it, never paste it in chat/docs/slides. Rotate the key after the hackathon.

Open items

  • Which provider is the API key for (Azure OpenAI / Gemini / other)? Need the endpoint URL + model/deployment name to wire the judge agent (JUDGE_PROVIDER=llm is ready and waiting for those three env vars).
  • backend_starter/ (Allen's branch) uses the old, simpler event schema — upgrade it to the spec schema or retire it so nobody builds against the old shape.

Resolved since kickoff

  • Token threshold: per-trace cumulative (implemented in orca/tripwires.py).
  • Compliance report contents: chain verification, enforcement record with OWASP tags, human oversight with reviewer names, quality reviews, cost attribution (orca/compliance.py; GET /report.md).
  • Cross-framework enforcement: proven with a real LangGraph graph — guarded tools pass the Policy Gate before executing (orca/adapters.py, test_adapters.py).