flowchart LR
    subgraph agent["Agent runtime (unchanged)"]
        direction TB
        P["Policies and routines<br/>decide what the agent should do"]
        R["LLM router"]
        M1["mcps: operator-read"]
        M2["mcps: operator-write"]
    end

    subgraph gh["gatehouse, one process per profile"]
        direction TB
        A["1 Bearer check<br/>MCP_API_KEY on every request"]
        F["2 Profile<br/>only granted tools are listed"]
        X["3 Rules<br/>allow, deny or handoff"]
        I["4 Idempotency<br/>a retried write returns the first result"]
        K["5 Mask<br/>fields and PII in free text"]
        L["6 Audit<br/>one JSON line per call"]
        A --> F --> X --> I
        K --> L
    end

    subgraph up["Customer's MCP server (unchanged)"]
        direction TB
        U1["Player accounts"]
        U2["Support desk"]
        U3["KYC provider"]
        U4["Payments"]
    end

    M2 -- "tools/call" --> A
    I -- "allowed call" --> up
    up -- "raw result" --> K
    L -- "masked result" --> M2
    X -. "handoff: needs_human as data,<br/>upstream untouched" .-> M2

flowchart TD
    C(["tools/call from the agent"]) --> K{"Bearer key valid?"}
    K -- no --> E1["401, nothing runs"]
    K -- yes --> P{"Tool in this profile?"}
    P -- no --> D1["not_allowed, rule: profile<br/>(enforced even in shadow mode)"]
    P -- yes --> R{"First matching rule"}
    R -- "deny or handoff" --> S{"mode: shadow?"}
    S -- no --> D2["return the error as data<br/>handoff names initiate_human_handoff"]
    S -- yes --> Q
    R -- "no match: allow" --> Q{"Same write seen<br/>inside the window?"}
    R -- "rule cannot read an argument" --> D3["deny, fail closed"]
    Q -- yes --> RP["return the first result, run nothing"]
    Q -- no --> UP["call the upstream tool"]
    UP --> MK["mask the result:<br/>named fields, PII in text,<br/>withhold images and files"]
    MK --> OUT(["masked result to the agent"])
    D1 & D2 & D3 & RP & OUT --> AU[("audit.jsonl<br/>masked arguments, decision, rule, ms")]

sequenceDiagram
    autonumber
    participant Player
    participant Agent as Agent (policies, router)
    participant Gate as gatehouse (support-write)
    participant PAM as Player accounts
    participant Human as Support person

    Player->>Agent: "Please pay my winnings to a new IBAN"
    Agent->>Gate: tools/call update_bank_account(P-1001, ES76...)
    Gate->>Gate: rule bank-account-changes-go-to-a-human matches
    Gate-->>Agent: {"error": "needs_human", "rule": "...", "next": "initiate_human_handoff"}
    Note over Gate,PAM: The player account is never called
    Agent->>Human: built-in:initiate_human_handoff(reason)
    Human->>PAM: verifies identity, changes the IBAN
    Agent->>Gate: tools/call get_player(P-1001)
    Gate->>PAM: get_player(P-1001)
    PAM-->>Gate: full record, IBAN, phone, date of birth
    Gate-->>Agent: iban ****5766, phone ****5678, date of birth dropped

pip install -e .
python examples/igaming/demo.py

support-read   sees 3 of 9 upstream tools: get_player, get_ticket, list_transactions
support-write  sees 8 of 9 upstream tools: add_ticket_comment, apply_bonus, close_ticket, get_player, ...

  look up the player                     get_player           -> iban ****1332, phone ****5678, email ***@example.com, dropped date_of_birth, document_number
  read a ticket with an IBAN in it       get_ticket           -> "Withdrawal of 40 EUR pending 3 days. Please send it to ****1332, or call me on ****5678."
  player asks to change the payout IBAN  update_bank_account  -> NEEDS_HUMAN  [bank-account-changes-go-to-a-human]
  10 EUR goodwill bonus                  apply_bonus          -> {"bonus_id": "B-9001", ..., "new_balance_eur": 52.5}
  model retries after a timeout          apply_bonus          -> {"bonus_id": "B-9001", ..., "new_balance_eur": 52.5}
  120 EUR bonus                          apply_bonus          -> NEEDS_HUMAN  [bonus-above-50-needs-a-supervisor]
  player asks to self-exclude            set_self_exclusion   -> NEEDS_HUMAN  [self-exclusion-goes-to-a-human]
  close with no resolution               close_ticket         -> NOT_ALLOWED  [close-only-with-a-resolution]
  a tool in no profile                   export_player_data   -> NOT_ALLOWED  [profile]

balance after two identical 10 EUR calls: 52.50 EUR (started at 42.50)

upstream: http://operator-mcp:8765/mcp    # any streamable-http MCP server, or a local .py file
api_key: ${MCP_API_KEY}
audit_log: audit.jsonl

profiles:
  support-read:  { tools: [get_player, list_transactions, get_ticket] }
  support-write: { tools: [get_player, list_transactions, get_ticket, add_ticket_comment,
                           close_ticket, apply_bonus, update_bank_account, set_self_exclusion] }

mask:
  fields: { iban: last4, phone: last4, email: domain, date_of_birth: drop, document_number: drop }
  patterns: [iban, card, email, phone]

rules:
  - id: bank-account-changes-go-to-a-human
    tools: [update_bank_account]
    action: handoff
    reason: Bank account changes are always handled by a person.
  - id: bonus-above-50-needs-a-supervisor
    tools: [apply_bonus]
    when: { amount_eur: { gt: 50 } }
    action: handoff

idempotency:
  tools: [apply_bonus, add_ticket_comment, update_bank_account]
  window_seconds: 600

gatehouse examples/igaming/gatehouse.yaml --profile support-write --port 8766

agent_config:
  mcps:
    - id: operator                       # tools appear as operator:get_player
      hostname: http://gatehouse-support-write
      port: 8766
      api_key: ${GATEHOUSE_KEY}

iai mcps create gatehouse-support-write --image-name gatehouse --image-tag v1 --port 8766

python -m unittest discover -s tests