# Project export: Agent Arcade This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small. ## Project metadata - Hackathon: OpenAI Build Week - Tagline: An inspectable playground where AI agents solve logic and visual puzzles. - Devpost: https://devpost.com/software/agent-arcade - GitHub: https://github.com/Gaurav17Joshi/AgentArcade - Demo: https://agentarcade.onrender.com/ - Video: https://www.youtube.com/embed/JIc6IHXySzk?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent - Team: 1 GitHub contributor(s) — Gaurav Joshi (30 commits) ## Devpost submission (written by the team) No Devpost description available. ## README (from the GitHub repository) # Agent Arcade **An inspectable playground where AI agents solve logic and visual puzzles.** [Live demo](https://agentarcade.onrender.com) · [Devpost project](https://devpost.com/software/agent-arcade) · [Technical report](AGENT_ARCADE_REPORT.md) ![Agent Arcade: a Sokoban board beside the live public agent journal](assets/Agent_example.png) Agent Arcade turns puzzles into small, controlled environments for watching an agent work. Instead of showing only a final answer, it renders the puzzle board, validates each action, and records a concise public journal of observations, plans, explorer branches, helper work, action batches, token use, and estimated cost. ## What it includes - **Logic worlds:** Sokoban, maze, and Klotski with explicit, rule-validated actions. - **Visual worlds:** real-image Jigsaw puzzles that require visible fragment matching. - **Computer-control worlds:** cursor-driven Klotski and Jigsaw variants that accept literal validated drags on a virtual screen. - **Inspectable live runs:** a model can observe, make a short public plan, create focused explorer branches, write/run a restricted Python helper, commit actions, and re-observe the result. - **Bring your own key:** visitors use their own OpenAI or Anthropic key; public deployments do not contain an author key or store visitor keys. ## Quick start ### Requirements - Node.js **20–24** - An Anthropic API key for live Claude puzzle runs; an OpenAI key may also be used for provider connection checks. ### Run locally ```bash git clone https://github.com/Gaurav17Joshi/AgentArcade.git cd AgentArcade npm install cp .env.example .env.local ``` Open `.env.local` in a local editor and add only the keys you intend to use: ```bash ANTHROPIC_API_KEY=your_anthropic_key OPENAI_API_KEY=your_openai_key ``` Then start the app: ```bash npm start ``` Open [http://127.0.0.1:4173](http://127.0.0.1:4173). If that port is busy, run `PORT=4174 npm start` instead. Never commit `.env.local` or paste a key into chat. ### Run a live agent 1. Choose a puzzle and level from **Puzzles**. 2. Open **API keys** and add a personal key for the current browser tab, or use your local `.env.local` setup. 3. Open **Agents**, choose a provider/model and run mode, then start the agent. 4. Watch the live board and open **View trace** to inspect the complete public journal. Explorer branches appear in the Agents panel. The hosted app at [agentarcade.onrender.com](https://agentarcade.onrender.com) uses browser-session BYOK mode. A user key is sent only for that provider request, is not saved by Agent Arcade, and is cleared when the page reloads. ## How the agent loop works Every environment exposes a current observation, a restricted action surface, an action validator, a solved-state check, and a renderer. The runtime follows this loop: ```text observe → publish a concise public checkpoint → optionally explore or use a helper → propose a short action batch → validate → animate → observe again ``` Logic puzzles use structured moves. Visual cursor puzzles render a virtual screen and accept only valid mouse drags against its coordinates. The journal is deliberately a human-readable public trace, not hidden chain-of-thought. Boards update while the agent works and are marked solved only after the environment's actual solved-state check passes. Small Python helpers may be written in an isolated temporary workspace for calculations such as search or board verification. The restricted runner has short CPU/memory limits and no filesystem, shell, browser, network, environment-variable, or API-key access. ## Built with Codex and GPT-5.6 Agent Arcade was built end-to-end with **Codex**. Most implementation happened in a single Codex session using **GPT-5.6 Terra at Extra High reasoning**. Codex accelerated the project from the initial product sketch through: - designing the puzzle-environment and agent-loop contract; - implementing the vanilla HTML/CSS/JavaScript interface and Node streaming server; - adding Sokoban, maze, Klotski, Jigsaw, and virtual-cursor environments; - building the public trace, explorer-branch, sandbox-helper, validation, and rendering flows; - diagnosing real provider-run failures, testing in the browser, refining the UI, and deploying to Render; - preparing the reports, demo video, captions, and AI-generated narration for the OpenAI Build Week submission. GPT-5.6 Terra was used as the high-reasoning implementation partner inside Codex; the project itself remains a BYOK multi-provider playground. Anthropic currently powers the live puzzle-runner adapter, while the OpenAI connection is available for key/model validation and can be extended with a live puzzle adapter. ## Verification Run the lightweight syntax check before making a change: ```bash npm run check ``` For a manual end-to-end check, start the server, select a Sokoban level, add a personal Anthropic key, run an agent, and verify that the board and **View trace** journal advance together. ## Deploying The repository contains a Render Blueprint for one HTTPS Node web service. It hosts both the browser client and Node agent server in BYOK mode; no author API key needs to be deployed. See [RENDER_DEPLOY.md](RENDER_DEPLOY.md) for the deployment flow. ## Further documentation - [Product and technical design report](AGENT_ARCADE_REPORT.md) - [Implementation report](IMPLEMENTATION_REPORT.html) - [Local API-key setup and run modes](API_SETUP.md) - [Render deployment guide](RENDER_DEPLOY.md) - [Puzzle and asset sources](SOURCES.md) ## Detected evidence (automated analysis) Indexed codebase: 12 recognized source files, 191 KB. - CSS (language) — detected in the code - HTML (language) — detected in the code - JavaScript (language) — detected in the code - Python (language) — detected in the code - Node.js (technology) — claimed on Devpost, not found in the code ## Codebase structure (from repository index) ### Files (16 of 16) ``` .env.example .gitignore AGENT_ARCADE_REPORT.md agent_python_sandbox.py API_SETUP.md app.js FREE_AGENT_LOOP_REPORT.html IMPLEMENTATION_REPORT.html index.html package.json README.md RENDER_DEPLOY.md render.yaml server.mjs SOURCES.md styles.css ``` ### Dependencies No dependency index available. ### Recent commits (newest first) - Document setup and Codex workflow - Clarify live agent provider support - Clarify both BYOK providers - Improve Fable visual jigsaw recovery - Add practical Agent Arcade guide - Guide Jigsaw agents row by row - Crop Jigsaw artwork to a square - Make Jigsaw a real visual placement task - Follow live run journal updates - Retry transient Anthropic agent requests - Add deep long-horizon agent mode - Harden live agent tool loop - Fix hosted BYOK provider header - Refine Sokoban warehouse artwork - Refine virtual cursor capture - Add BYOK hosting flow and pixel Sokoban - Polish Sokoban and add cursor puzzle families - Add virtual mouse puzzle controls - Prevent live agent helper loops - Improve agent journals and add restricted Python helpers ## Key source files (fetched from GitHub, selected and truncated for size) ### RENDER_DEPLOY.md ```markdown # Publish Agent Arcade on Render This repository is configured for a single Render **Web Service**: it serves the browser app and the Node agent routes from the same HTTPS URL. ## What the public site does with keys - It is **BYOK-only**: `render.yaml` sets `BYOK_ONLY=true`. - Do **not** add `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` to Render. - A visitor enters a key in the **API keys** drawer. The key is held only in that page's memory, sent over HTTPS only for the visitor's provider request, and cleared on reload. - The server does not write, log, or persist visitor keys. ## Deploy 1. Create or sign in to [Render](https://render.com/), then choose **New → Blueprint**. 2. Connect the `Gaurav17Joshi/AgentArcade` GitHub repository and select its `main` branch. 3. Render reads [`render.yaml`](render.yaml). Confirm the **Free** instance and create the service. 4. When the deploy completes, open the generated `https://…onrender.com` link. 5. Verify `https://your-service.onrender.com/api/health` returns `{"ok":true,"mode":"byok"}`. The Free web-service option is suitable for the hackathon link. It spins down after 15 minutes idle and can take about a minute to wake up, so open the URL shortly before a judging demo. See [Render's free-tier documentation](https://render.com/docs/free). Every later push to `main` can automatically redeploy the service after GitHub is connected. ``` ### SOURCES.md ```markdown # Asset and puzzle sources ## Jigsaw reference images - File: `assets/cat.jpg` - Source: [Unsplash image delivery URL](https://images.unsplash.com/photo-1518791841217-8f162f1e1131?auto=format&fit=crop&w=1200&q=85) - File: `assets/dog.jpg` — [Golden retriever photograph, CC0](https://commons.wikimedia.org/wiki/File:Image_of_golden_retriever.jpg). - File: `assets/mona-lisa.jpg` — [Mona Lisa by Leonardo da Vinci, public-domain reproduction](https://commons.wikimedia.org/wiki/File:Mona_Lisa.jpg). - File: `assets/great-wave.jpg` — [The Great Wave off Kanagawa, public-domain reproduction](https://commons.wikimedia.org/wiki/File:Great_Wave_off_Kanagawa_restored.jpg). - File: `assets/starry-night.jpg` — [The Starry Night by Vincent van Gogh, public-domain reproduction](https://commons.wikimedia.org/wiki/File:TheStarryNightByVincentVanGogh.jpg). They are stored locally so Jigsaw works without third-party image requests and so the cursor runner can safely capture the complete visual board. The app sends the selected reference image to a visual-model provider only when the user explicitly starts a reference-enabled live run. ## Sokoban levels - `Microban 02`, `31`, `38`, and `47` are imported from the [Microban level text in Still Yet Another Sokoban](https://github.com/davidjoffe/sokoban/blob/main/data/sokoban/levels/microban.txt), with only board-safe exterior padding added where needed. The repository README describes its default 90-level collection as public domain. - `Reference warehouse` is an original playable interpretation inspired by the supplied `Images/Sokoban1.png` sketch, not a claim of an exact transcription. ## Klotski levels - `Beginner 2` and the three `Advanced` boards are playable long-block interpretations of the supplied `Images/klotski3.jpeg` through `Images/klotski6.jpeg`. They preserve the requested rule: a rectangular tile slides only along its longer axis; no rotations or diagonal moves are allowed. - The numbered-tile convention and classic 4×5 Klotski family are documented by [Klotski.org](https://www.klotski.org/). Agent Arcade deliberately uses a 6×6 long-block variant to match the supplied reference boards and make each command legible as `1R`, `2U`, and so on. ## Maze levels - The expert maze difficulty, dense dead-end style, and 20–30 cell rectangular target sizes are based on the freely available [Maze Printables expert collection](https://mazeprintables.com/). Agent Arcade transcribes compact grid versions so they remain keyboard- and agent-playable rather than embedding the source artwork. ## Model presets - Anthropic preset IDs and displayed families are taken from Anthropic’s [model overview](https://platform.claude.com/docs/en/about-claude/models/overview). In particular, current Claude 4.6+ aliases use dateless IDs such as `claude-sonnet-5`. - OpenAI preset IDs are taken from the official [OpenAI model documentation](https://developers.openai.com/api/docs/models), including `gpt-5.6-sol`, `gpt-5.6-terra`, [truncated — 20 more characters] ``` ### package.json ``` { "name": "agent-arcade", "private": true, "version": "1.0.0", "description": "Inspectable agent puzzle environments", "type": "module", "engines": { "node": ">=20 <25" }, "scripts": { "start": "node server.mjs", "check": "node --check app.js && node --check server.mjs" } } ``` ### render.yaml ```yaml services: - type: web name: agent-arcade runtime: node plan: free buildCommand: npm install startCommand: npm start healthCheckPath: /api/health envVars: - key: NODE_VERSION value: "20" - key: NODE_ENV value: production - key: BYOK_ONLY value: "true" ``` ### agent_python_sandbox.py ```python #!/usr/bin/env python3 """Restricted algorithm helper for Agent Arcade workspaces. This is intentionally not a general Python shell. It accepts small, pure calculation scripts and rejects filesystem, network, process, reflection, and private-attribute access before execution. """ import ast import resource import sys ALLOWED_MODULES = { "bisect", "collections", "functools", "heapq", "itertools", "json", "math", "operator", "re", "statistics", } BANNED_NAMES = { "__builtins__", "__import__", "breakpoint", "compile", "delattr", "dir", "eval", "exec", "exit", "getattr", "globals", "help", "input", "locals", "open", "quit", "setattr", "type", "vars", "object", "super", "os", "sys", "subprocess", "socket", "pathlib", "shutil", "builtins", "importlib", "ctypes", "multiprocessing", "threading", "asyncio", "requests", "urllib", "http", "pickle", "marshal", } class PolicyError(Exception): pass class Policy(ast.NodeVisitor): def visit_Import(self, node): for alias in node.names: if alias.name not in ALLOWED_MODULES: raise PolicyError(f"import {alias.name!r} is not allowed") self.generic_visit(node) def visit_ImportFrom(self, node): if node.level or node.module not in ALLOWED_MODULES: raise PolicyError(f"import from {node.module!r} is not allowed") if any(alias.name == "*" for alias in node.names): raise PolicyError("star imports are not allowed") self.generic_visit(node) def visit_Name(self, node): if node.id.startswith("__") or node.id in BANNED_NAMES: raise PolicyError(f"name {node.id!r} is not allowed") self.generic_visit(node) def visit_Attribute(self, node): if node.attr.startswith("_"): raise PolicyError("private attributes are not allowed") self.generic_visit(node) def visit_ClassDef(self, node): raise PolicyError("classes are not allowed in helper scripts") def visit_With(self, node): raise PolicyError("with blocks are not allowed in helper scripts") def visit_AsyncFunctionDef(self, node): raise PolicyError("async code is not allowed in helper scripts") def visit_Await(self, node): raise PolicyError("async code is not allowed in helper scripts") class Output: def __init__(self): self.parts = [] self.size = 0 def write(self, text): text = str(text) remaining = 8000 - self.size if remaining <= 0: return self.parts.append(text[:remaining]) self.size += len(text[:remaining]) def print(self, *values, sep=" ", end="\n"): self.write(sep.join(str(value) for value in values) + end) def value(self): return "".join(self.parts).strip() or "(helper completed without stdout)" def safe_import(name, globals=None, locals=None, fromlist=(), level=0): if level or name not in ALLOWED_MODULES: raise ImportError(f"module {name!r} is not available in this helper sandbox") return __import__(name, globals, locals, fromlist, level) def limit_resources(): try: resource.setrlimit(resource.RLIMIT_CPU, (2, 2)) resource.setrlimit(resource.RLIMIT_AS, (96 * 1024 * 1024, 96 * 1024 * 1024)) except (OSError, ValueError): pass SAFE_BUILTINS = { "abs": abs, "all": all, "any": any, "bool": bool, "dict": dict, "enumerate": enumerate, "filter": filter, "float": float, "int": int, "len": len, "list": list, "map": map, "max": max, "min": min, "range": range, "repr": repr, "reversed": reversed, "round": round, "set": set, "sorted": sorted, "str": str, "sum": sum, "tuple": tuple, "zip": zip, "Exception": Exception, "ValueError": ValueError, "print": None, "__import__": safe_import, } def main(): if len(sys.argv) != 2: raise SystemExit("usage: agent_python_sandbox.py helper.py") with open(sys.argv[1], "r", encoding="utf-8") as source_file: source = source_file.read() if len(source) > 6000: raise PolicyError("helper scripts are limited to 6000 characters") tree = ast.parse(source, filename="agent-helper.py", mode="exec") Policy().visit(tree) limit_resources() output = Output() builtins = dict(SAFE_BUILTINS) builtins["print"] = output.print namespace = {"__builtins__": builtins, "__name__": "__agent_helper__"} exec(compile(tree, "agent-helper.py", "exec"), namespace, namespace) print(output.value()) if __name__ == "__main__": try: main() except (PolicyError, SyntaxError, Exception) as error: print(f"HELPER_ERROR: {error}") raise SystemExit(1) ``` ### IMPLEMENTATION_REPORT.html ```html Agent Arcade — Implementation Report

AGENT ARCADE · IMPLEMENTATION REPORT

Agent Arcade · redesigned puzzle-first build

This report describes the runnable first build in this repository. Open index.html to use it.

What was built

How the Sokoban agent works

The local demo agent receives the canonical grid state, runs breadth-first search over legal player moves and crate pushes, then visibly applies its found route one action at a time. This makes the browser demo deterministic, free to run, and testable without an API key.

observe board → find shortest legal state path → animate actions
→ record timeline/trace → check all goals → complete

For the no-key demo, “Delegate alternatives” creates visible child-workspace reports. With Claude selected, the local server instead runs a real bounded tool loop for Sokoban, Maze, and Klotski: observe board, optionally spawn an explorer, write a temporary helper artifact, and choose short batches of legal moves. The Agents drawer exposes three explicit live-run styles: Free agent has no route hints; Action checker tests only a batch the agent has proposed itself and never searches; Solver aid exposes a local deterministic completion route only when the agent explicitly requests it. Free agent is the default. Every batch carries a concise public Reason: tied to the visible board. Each action streams to the browser while the agent remains active, so it can inspect the newly visible state and continue. The browser shows only short public activity and explorer reports, not private reasoning.

Visual and interaction design

The Sokoban board uses visual crate, goal, wall, and player affordances inspired by Images/Sokoban1.png, without copying its image content. The Klotski board uses a wood, grid, highlighted target, and exit treatment inspired by Images/Klotski1.jpeg and Images/Klotski2.jpeg.

Run it locally

cd /Users/gauravjoshi/Desktop/R/AgentArcade
node server.mjs
# open http://127.0.0.1:4173

No package installation is needed. See API_SETUP.md to add your own local OpenAI and Anthropic keys without sharing them in chat.

Live provider and jigsaw checks

The current curated Anthropic preset is claude-sonnet-5; the dated string claude-sonnet-5-20251001 is diagnosed as invalid. Sonnet 5 was tested in-browser on Two Crates: it observed, used the then-available route helper, stated an observable reason, streamed a three-move final batch, and solved in seven verified moves for an estimated $0.0141. Claude Haiku was also tested through the live Maze and Klotski streams: Maze solved in a reasoned 4-action batch and Klotski solved a numbered 6-action route in two batches. A live 5 × 5 cat jigsaw call produced a visual inventory (eyes, ears, chest, foreground), a harness note, and five five-tile placement batches for an estimated $0.0025—instead of a bare tile-number dump. The cat asset and level provenance are recorded in SOURCES.md.

Known next runtime layer

Included nowNext integration
Playable puzzle engines, compact level picker, ten Sokoban boards, expert mazes, and five Klotski boardsOpenAI puzzle runner using the Agents SDK/custom model adapter
C [truncated — 1193 more characters] ``` ### index.html ```html Agent Arcade
Agent
Arcade

LOGIC LAB · LEVEL 02

Sokoban · Two cratesStructured logic
Use arrows to move. Push every crate onto a target.
00moves
00pushes
READYagent status
—estimated api cost
LAST COMMAND—

HOW AGENT ARCADE WORKS

Give an agent
a puzzle to solve.

Agent Arcade is a set of inspectable logic and visual puzzle environments. The model sees the selected board, works through it in a private workspace, and publishes a readable record of the decisions that change the puzzle.

  1. 1 · Choose a puzzleSelect a family and level from the six cards beside this guide.
  2. 2 · Add your own API keyOpen API keys in the top bar and add an Anthropic and/or OpenAI key. Keys stay only in this browser tab. Anthropic powers the live puzzle agents; OpenAI is available for a session-key check.
  3. 3 · Start and inspectOpen Agents, choose an Anthropic model, and press Run this agent. Explorer branches appear in that panel and under Main agent; use View trace for the public run journal.