# penguinpecker/agentgames-2026 architecture

> Architecture diagram of the GitHub repository penguinpecker/agentgames-2026, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/penguinpecker/agentgames-2026
- Repository: https://github.com/penguinpecker/agentgames-2026

## Overview

This repository implements a signed HTTPS game agent for Steal the VFY and Proof Gatekeeper. The principal workflow authenticates and validates an incoming envelope, routes it to a game-specific handler, and returns a signed answer. Steal computes a policy action and Groth16 proof; Gatekeeper checks trap conditions, tracks proof replays, and generates a statement proof. Vercel also archives competition exchanges in Blob. The local server is an alternate wrapper around the transport core. Edges reflect README statements and shown imports or calls; circuit artifacts are external inputs, and their runtime details are not represented as inspected source.

Main entry points: [`src/gatekeeper-task.mjs`](https://github.com/penguinpecker/agentgames-2026/blob/main/src/gatekeeper-task.mjs) (Task evaluation), [`src/handler.mjs`](https://github.com/penguinpecker/agentgames-2026/blob/main/src/handler.mjs) (Request handler), [`api/agent.mjs`](https://github.com/penguinpecker/agentgames-2026/blob/main/api/agent.mjs) (Vercel endpoint), [`src/handlers.mjs`](https://github.com/penguinpecker/agentgames-2026/blob/main/src/handlers.mjs) (Game dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_transport["Signed transport"]
  node_api["Vercel endpoint<br/>[agent.mjs]"]
  node_transport_core["Request handler<br/>[handler.mjs]"]
  node_security["HMAC and time checks<br/>[security.mjs]"]
  node_game_handlers["Game dispatch<br/>[handlers.mjs]"]
end

subgraph group_steal["Steal the VFY"]
  node_steal_turn["Turn strategy and proof<br/>[steal.mjs]"]
  node_policy["Policy rules<br/>[policy.mjs]"]
end

subgraph group_gatekeeper["Proof Gatekeeper"]
  node_gatekeeper_task["Task evaluation"]
  node_statement_checks["Trap checks<br/>[gatekeeper.mjs]"]
  node_gatekeeper_proofs["Circuit proof verification<br/>[proofs.mjs]"]
  node_task_id_encoding["Task ID encoding<br/>[gk-encoding.mjs]"]
end

subgraph group_persistence["Persistence"]
  node_seen_set[("Accepted proof set<br/>[seen.mjs]")]
  node_exchange_archive["Exchange archive<br/>[seen.mjs]"]
end

node_game_platform(("Game platform"))
node_vercel_blob[("Vercel Blob")]

node_game_platform -->|"sends tasks"| node_api
node_api -->|"passes request"| node_transport_core
node_transport_core -->|"authenticates and checks time"| node_security
node_transport_core -->|"dispatches task"| node_game_handlers
node_game_handlers -->|"runs turn"| node_steal_turn
node_game_handlers -->|"runs task"| node_gatekeeper_task
node_steal_turn -->|"computes action"| node_policy
node_gatekeeper_task -->|"evaluates input"| node_statement_checks
node_gatekeeper_task -->|"checks and marks replay"| node_seen_set
node_gatekeeper_task -->|"creates proof"| node_gatekeeper_proofs
node_gatekeeper_task -->|"encodes task ID"| node_task_id_encoding
node_seen_set -->|"reads and writes"| node_vercel_blob
node_transport_core -->|"archives competition reply"| node_exchange_archive
node_api -->|"provides archive callback"| node_exchange_archive
node_exchange_archive -->|"stores exchanges"| node_vercel_blob

click node_api "https://github.com/penguinpecker/agentgames-2026/blob/main/api/agent.mjs"
click node_transport_core "https://github.com/penguinpecker/agentgames-2026/blob/main/src/handler.mjs"
click node_security "https://github.com/penguinpecker/agentgames-2026/blob/main/src/security.mjs"
click node_game_handlers "https://github.com/penguinpecker/agentgames-2026/blob/main/src/handlers.mjs"
click node_steal_turn "https://github.com/penguinpecker/agentgames-2026/blob/main/src/steal.mjs"
click node_policy "https://github.com/penguinpecker/agentgames-2026/blob/main/src/policy.mjs"
click node_gatekeeper_task "https://github.com/penguinpecker/agentgames-2026/blob/main/src/gatekeeper-task.mjs"
click node_statement_checks "https://github.com/penguinpecker/agentgames-2026/blob/main/src/gatekeeper.mjs"
click node_gatekeeper_proofs "https://github.com/penguinpecker/agentgames-2026/blob/main/src/proofs.mjs"
click node_task_id_encoding "https://github.com/penguinpecker/agentgames-2026/blob/main/src/gk-encoding.mjs"
click node_seen_set "https://github.com/penguinpecker/agentgames-2026/blob/main/src/seen.mjs"
click node_exchange_archive "https://github.com/penguinpecker/agentgames-2026/blob/main/src/seen.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_transport_core,node_security,node_game_handlers toneBlue
class node_steal_turn,node_policy,node_vercel_blob toneAmber
class node_gatekeeper_task,node_statement_checks,node_gatekeeper_proofs,node_task_id_encoding toneMint
class node_seen_set,node_exchange_archive toneRose
class node_game_platform toneIndigo
```

## Components

### Signed transport

- [Vercel endpoint](https://github.com/penguinpecker/agentgames-2026/blob/main/api/agent.mjs): `api/agent.mjs`
- [Request handler](https://github.com/penguinpecker/agentgames-2026/blob/main/src/handler.mjs): `src/handler.mjs`
- [HMAC and time checks](https://github.com/penguinpecker/agentgames-2026/blob/main/src/security.mjs): `src/security.mjs`
- [Game dispatch](https://github.com/penguinpecker/agentgames-2026/blob/main/src/handlers.mjs): `src/handlers.mjs`

### Steal the VFY

- [Turn strategy and proof](https://github.com/penguinpecker/agentgames-2026/blob/main/src/steal.mjs): `src/steal.mjs`
- [Policy rules](https://github.com/penguinpecker/agentgames-2026/blob/main/src/policy.mjs): `src/policy.mjs`

### Proof Gatekeeper

- [Task evaluation](https://github.com/penguinpecker/agentgames-2026/blob/main/src/gatekeeper-task.mjs): `src/gatekeeper-task.mjs`
- [Trap checks](https://github.com/penguinpecker/agentgames-2026/blob/main/src/gatekeeper.mjs): `src/gatekeeper.mjs`
- [Circuit proof verification](https://github.com/penguinpecker/agentgames-2026/blob/main/src/proofs.mjs): `src/proofs.mjs`
- [Task ID encoding](https://github.com/penguinpecker/agentgames-2026/blob/main/src/gk-encoding.mjs): `src/gk-encoding.mjs`

### Persistence

- [Accepted proof set](https://github.com/penguinpecker/agentgames-2026/blob/main/src/seen.mjs): `src/seen.mjs`
- [Exchange archive](https://github.com/penguinpecker/agentgames-2026/blob/main/src/seen.mjs): `src/seen.mjs`

### Other components

- **Game platform**
- **Vercel Blob**

## Connections

- Game platform → Vercel endpoint: sends tasks (evidence: `README.md`)
- Vercel endpoint → Request handler: passes request (evidence: `api/agent.mjs`)
- Request handler → HMAC and time checks: authenticates and checks time (evidence: `src/handler.mjs`)
- Request handler → Game dispatch: dispatches task (evidence: `api/agent.mjs`)
- Game dispatch → Turn strategy and proof: runs turn (evidence: `src/handlers.mjs`)
- Game dispatch → Task evaluation: runs task (evidence: `src/handlers.mjs`)
- Turn strategy and proof → Policy rules: computes action (evidence: `src/steal.mjs`)
- Task evaluation → Trap checks: evaluates input (evidence: `src/gatekeeper-task.mjs`)
- Task evaluation → Accepted proof set: checks and marks replay (evidence: `src/gatekeeper-task.mjs`)
- Task evaluation → Circuit proof verification: creates proof (evidence: `src/gatekeeper-task.mjs`)
- Task evaluation → Task ID encoding: encodes task ID (evidence: `src/gatekeeper-task.mjs`)
- Accepted proof set → Vercel Blob: reads and writes (evidence: `src/seen.mjs`)
- Request handler → Exchange archive: archives competition reply (evidence: `src/handler.mjs`)
- Vercel endpoint → Exchange archive: provides archive callback (evidence: `api/agent.mjs`)
- Exchange archive → Vercel Blob: stores exchanges (evidence: `src/seen.mjs`)
