Restore full Space app with bucket model support

.dockerignore

@@ -0,0 +1,21 @@
+.venv/
+.uv-cache/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.codegraph/
+.git/
+.gitignore
+.DS_Store
+*.pyc
+*.pyo
+.pytest_cache/
+.agents/
+tests_python/
+docs/
+scripts/
+screenshots/
+*.log
+.env
+.env.*

.editorconfig

@@ -0,0 +1,24 @@
+# EditorConfig - https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = tab
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{yaml,yml}]
+indent_style = space
+indent_size = 2
+
+[*.json]
+indent_style = tab
+indent_size = 2
+
+[Makefile]
+indent_style = tab

.gitignore

@@ -0,0 +1,15 @@
+.env
+.env.*
+!.env.example
+
+.venv
+.uv-cache
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.codegraph/
+
+.DS_Store
+Thumbs.db
+.agents/

.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "langchain-docs": {
+      "type": "http",
+      "url": "https://docs.langchain.com/mcp"
+    }
+  }
+}

AGENTS.md

@@ -0,0 +1,198 @@
+# AGENTS.md
+
+## Communication Style
+
+Use caveman-style responses for this repo.
+
+Rules:
+
+- Be terse.
+- Drop filler, pleasantries, hedging, and long setup.
+- Keep technical terms exact.
+- Keep code blocks unchanged.
+- Use fragments when clear.
+- Prefer arrows for cause/effect: `X -> Y`.
+- Pattern: `[thing] [action] [reason]. [next step].`
+- Do not sacrifice correctness, warnings, or exact error text.
+- For destructive ops, security warnings, or complex sequences where brevity risks misread, use full clarity first; resume terse style after.
+
+Example:
+
+```text
+Bug in auth middleware. Token expiry check uses `<` not `<=`. Fix:
+```
+
+## Project
+
+Agent Swarm Workbench is a Python-first agent swarm workbench. The project began as Vibecode Arena, but the active product is prompt-first: one user prompt becomes a persisted Run, a sandboxed Swarm builds a Codebase, and a separate Validator checks the result.
+
+Old SvelteKit, Cloudflare Worker, Bun, Wrangler, E2B, browser game files, and competition-arena concepts are legacy and should not be reintroduced for new features.
+
+Target product: a user provides one prompt, the system starts a persisted Run, a Coordinator/worker agent swarm performs the work in sandboxed workspaces, artifacts are archived, and a LangGraph Validator checks the result in a separate Validator sandbox.
+
+## Stack
+
+- Python 3.11+
+- FastAPI HTTP surface
+- Gradio UI mounted on the FastAPI ASGI app
+- LangChain DeepAgents runtime
+- OpenRouter model gateway via `langchain-openrouter`
+- DeepAgents sandbox backend, default Daytona via `langchain-daytona`
+- `langchain-quickjs` code interpreter middleware inside the DeepAgent loop
+- LangGraph Validator workflow
+- Upstash Redis REST for persisted Runs and Codebase archives
+- `requirements.txt` for Hugging Face Spaces pip install compatibility
+
+## Commands
+
+```bash
+uv run uvicorn app:app --host 127.0.0.1 --port 8790  # run unified ASGI app locally
+uv run python app.py                                  # run unified HF-style launcher
+python scripts/task.py test     # run Python tests
+python scripts/task.py harness -- --prompt "Build a tiny CLI" # run local scripted Agent Swarm Harness
+python scripts/task.py verify   # compulsory coding-agent gate: tests + Agent Swarm Harness
+python scripts/task.py smoke    # create local DeepAgent session without remote sandbox
+python scripts/task.py validator-smoke # exercise Validator graph against a local Codebase archive
+python scripts/task.py daytona-validator-smoke # exercise Validator graph in a live Daytona Validator sandbox
+python scripts/task.py clean    # remove Python caches
+```
+
+Direct equivalents:
+
+```bash
+uv run uvicorn app:app --host 127.0.0.1 --port 8790
+uv run python app.py
+uv run pytest tests_python
+```
+
+`scripts/task.py verify` is the built-in completion gate for coding agents such as Claude Code, Codex, OpenCode, and similar tools. It runs the Python test suite and then the local scripted Agent Swarm Harness. Use focused `test` or `harness` commands while iterating, but run `verify` before presenting code changes as complete.
+
+`scripts/task.py` includes `.env` when present and falls back to `UV_PROJECT_ENVIRONMENT=.venv`, `UV_CACHE_DIR=.uv-cache`, and `UV_LINK_MODE=copy`. The Makefile is a compatibility shim only.
+
+For serving the Hackathon demo, prefer direct `uv run uvicorn app:app ...` or `uv run python app.py` so the entrypoint is obvious.
+
+## Env
+
+```bash
+OPENROUTER_API_KEY=sk-or-...
+GEMINI_API_KEY=...
+NEBIUS_API_KEY=...
+HF_TOKEN=...
+DAYTONA_API_KEY=...
+DEEPAGENT_MODEL_PROVIDER=openrouter
+DEEPAGENT_MODEL=openai/o4-mini
+DEEPAGENT_MODEL_BASE_URL=
+DEEPAGENT_SANDBOX_PROVIDER=daytona
+DEEPAGENT_REQUIRE_EXECUTE_APPROVAL=0
+# DEEPAGENT_REQUIRE_TOOL_APPROVAL=1
+# DEEPAGENT_INTERRUPT_TOOLS=execute,write_file,edit_file
+VALIDATOR_SANDBOX_PROVIDER=local
+```
+
+`DEEPAGENT_SANDBOX_PROVIDER=local` is for smoke tests only. It uses `LocalShellBackend`, which is not isolated.
+
+`DEEPAGENT_REQUIRE_EXECUTE_APPROVAL=1` interrupts only `execute`. `DEEPAGENT_REQUIRE_TOOL_APPROVAL=1` interrupts `execute`, `write_file`, and `edit_file`. `DEEPAGENT_INTERRUPT_TOOLS` can choose a subset of those DeepAgents built-in tools.
+
+`VALIDATOR_SANDBOX_PROVIDER=daytona` is production-like Validator mode. It restores Codebase archives into a Daytona sandbox before running Validation checks.
+
+Users can choose model provider per Run in Gradio. Supported provider choices: `openrouter`, `gemini`, `nebius`, `huggingface`, `custom`, `local`. Model lists must be fetched from the provider/API endpoint at runtime using the supplied key; do not hardcode model options. Only selectable models whose fetched ID/name/metadata proves `<=32B` parameters are allowed. Unknown-size models are not selectable. User API keys and fetched catalogs may live only in process memory; do not persist in RunStore, Redis, DB, Gradio state, events, logs, or archives. "Refresh models" must clear and refetch provider cache. The public Gradio UI must require a user-supplied key for hosted providers and must not use server fallback API keys by default.
+
+## Module Map
+
+Active prompt-first modules:
+
+- `app.py`: Unified ASGI entrypoint. Mounts Gradio at `/` on the FastAPI app so the Hackathon demo has one process.
+- `arena/api.py`: FastAPI route module. Owns HTTP request/response models and translates service errors to HTTP errors.
+- `arena/service.py`: Unified application API. FastAPI, Gradio handlers, and tests should call this boundary.
+- `arena/run_flow.py`: `RunFlow` - prompt-first Run lifecycle conductor. Owns Swarm execution handoff, archive download, and Validator invocation.
+- `arena/run_journal.py`: `RunJournal` - Run mutation journal. Owns Run creation, Rejoin, status transitions, task/event persistence, updated timestamps, and Event stream publication.
+- `arena/run_store.py`: `InMemoryRunStore` and `RedisRunStore`. Owns Run record persistence and Rejoin tokens.
+- `arena/swarm_runtime.py`: `SwarmRuntime`. Owns live Run registration and delegates each active AgentSession to `SwarmRunSession`.
+- `arena/swarm_session.py`: `SwarmRunSession`. Owns prompt seeding, agent turns, user-test retries, and Workspace snapshot creation for one live Run.
+- `arena/sandbox_lease.py`: Sandbox lease module. Owns idle TTL, touch, and close behavior for costly Swarm Workspace and Validator sandbox resources.
+- `arena/agent.py`: DeepAgent factory. Owns model construction, subagents, sandbox backend adapter selection, and session lifecycle.
+- `arena/backyard_templates.py`: Backyard Demo Builder template registry. Owns template prompt, criteria, and demo checks.
+- `arena/model_provider.py`: Chat model provider factory. Owns OpenRouter, Gemini, Nebius, Hugging Face Router, custom OpenAI-compatible, and local model config.
+- `arena/model_catalog.py`: Provider model catalog adapters. Owns normalized model list fetching and TTL caching.
+- `arena/gradio_app.py`: Prompt-first Gradio shell for the Hackathon demo. Keep it thin over `ArenaService`.
+- `arena/gradio_presenter.py`: Gradio presentation adapter. Owns Run output tuple formatting, status HTML, download link HTML, and chat timeline HTML.
+- `arena/gradio_markup.py`: Static Gradio shell markup fragments.
+- `arena/gradio_run.py`: Prompt-first Run parsing and JSON summary helpers for Gradio.
+- `arena/harness.py`: Built-in Agent Swarm Harness. Default mode exercises `SwarmRuntime` with a scripted local DeepAgent-compatible session; live mode uses the real DeepAgent session factory.
+- `arena/validator_graph.py`: LangGraph Validator workflow for prompt-first Runs.
+- `arena/validator_plan.py`: Typed Validator plan module. Converts user tests and Validation checks into command and Stagehand steps for ValidatorGraph.
+- `arena/validator_executor.py`: Validator sandbox executor factory.
+- `arena/codebase_archive.py`: Local and Redis-backed durable Codebase archive store.
+- `arena/codebase_handoff.py`: Codebase handoff module. Owns Workspace snapshot, archive pointer validation, and restore into Validator sandbox backends.
+- `arena/codebase_executor.py`: Sandboxed command executor module for Codebase archives, used by `validator_executor.SandboxValidatorExecutor`.
+- `arena/thread_inspector.py`: Manual Thread inspection module for debug routes: ad-hoc AgentSession creation, messages, and sandbox file reads.
+- `arena/redis_client.py`: Neutral Redis primitives (`RedisClient`, `UpstashRedisRestClient`, `RedisStoreError`) shared by Run and Codebase stores.
+- `arena/run_models.py`: Prompt-first Run model import surface.
+- `arena/validation_models.py`: Validator model import surface.
+- `arena/service_payloads.py`: Shared service payload models.
+- `arena/skill_catalog.py`: Discovery for repository-bundled DeepAgents skills mounted at `/skills/`.
+- `arena/paths.py`: Shared filesystem path constants for the package.
+- `arena/smoke.py`: Local smoke entrypoints for `agent` and `validator` task targets.
+- `arena/models.py`: Prompt-first Run and Validator domain models. Prefer importing from `arena/run_models.py` and `arena/validation_models.py`.
+- `scripts/task.py`: Python task runner for dev, Gradio, tests, verify gate, harness runs, smoke checks, and cleanup.
+- `skills/`: DeepAgents skill source mounted at `/skills/` and loaded through progressive disclosure.
+- `requirements.txt`: HF Spaces-compatible dependency list mirrored from `pyproject.toml`.
+- `tests_python/`: Python test surface. Tests public modules, not the old TS tree.
+
+## Architecture Rules
+
+- Keep DeepAgent construction behind `create_session()` in `arena/agent.py`.
+- Keep chat model construction behind `create_chat_model()` in `arena/model_provider.py`.
+- Keep provider model listing behind `ModelCatalog` in `arena/model_catalog.py`.
+- Keep Backyard Demo Builder prompt/criteria/check defaults behind `backyard_templates.py`.
+- Keep prompt-first Run orchestration behind `RunFlow` in `arena/run_flow.py`.
+- Keep Run status, task, event, timestamp, Rejoin, and Event stream mutation behind `RunJournal` in `arena/run_journal.py`.
+- Keep DeepAgent Swarm execution behind `SwarmRuntime` in `arena/swarm_runtime.py`.
+- Keep per-Run AgentSession prompting, retries, and Workspace snapshot behavior behind `SwarmRunSession` in `arena/swarm_session.py`.
+- Keep sandbox idle TTL, touch, and close behavior behind `SandboxLeaseManager` in `arena/sandbox_lease.py`.
+- Keep Run persistence behind the `RunStore` protocol in `arena/run_store.py`.
+- Keep Codebase archive persistence behind the `CodebaseArchiveStore` protocol in `arena/codebase_archive.py`.
+- Keep Workspace snapshot and Validator sandbox restore behind `CodebaseHandoff` in `arena/codebase_handoff.py`.
+- Keep Validator orchestration in `arena/validator_graph.py` and Validator sandbox selection in `arena/validator_executor.py`.
+- Keep Validation check classification behind `ValidatorPlan` in `arena/validator_plan.py`.
+- Keep ad-hoc Thread/session/file inspection behind `ThreadInspector` in `arena/thread_inspector.py`; do not add manual AgentSession behavior to `ArenaService`.
+- Keep Redis primitives (`RedisClient`, `UpstashRedisRestClient`, `RedisStoreError`) in `arena/redis_client.py`.
+- New work should use Run/Swarm/Task/Artifact/Validator language, not Host/Participant/Match/Leaderboard/Judge/Score language.
+- Keep Gradio thin: handlers call `ArenaService`, presentation formatting lives in `gradio_presenter.py`, and static shell HTML lives in `gradio_markup.py`.
+- Keep sandbox provider choice behind `DEEPAGENT_SANDBOX_PROVIDER` and Validator provider choice behind `VALIDATOR_SANDBOX_PROVIDER`.
+- Default sandbox provider is Daytona; local backend must stay explicit.
+- Keep `/context/` on a protected non-executable route and `/workspace` on the executable sandbox backend.
+- Do not call provider SDKs from route handlers except through `arena.agent`.
+- Treat prompts, file paths, and model output as untrusted input.
+- Do not log secrets, prompt payloads containing secrets, or sandbox file contents by default.
+- Avoid pass-through modules. New modules must increase depth: small interface, useful behavior hidden behind it.
+
+## Quality Bar
+
+- Run `python scripts/task.py verify` before reporting coding work complete. This is compulsory for agent-authored changes because it exercises both the Python suite and the Agent Swarm Harness.
+- Run `python scripts/task.py test` for focused iteration while editing.
+- Run `python scripts/task.py smoke` when touching `arena/agent.py`.
+- Add tests for new route behavior or session lifecycle behavior.
+- Prefer stdlib before new deps. New deps need clear leverage.
+
+## Agent Skills
+
+### Issue Tracker
+
+Issues and PRDs live in GitHub Issues for this repo and use the `gh` CLI. See `docs/agents/issue-tracker.md`.
+
+### Triage Labels
+
+Use the default five-label triage vocabulary. See `docs/agents/triage-labels.md`.
+
+### Domain Docs
+
+Single-context repo: root `CONTEXT.md` plus ADRs in `docs/adr/`. See `docs/agents/domain.md`.
+
+### LangChain Docs MCP
+
+Use the LangChain documentation MCP for current LangChain, LangGraph, LangSmith, and DeepAgents docs. Project config lives in `.mcp.json`; workflow notes live in `docs/agents/langchain-docs.md`.
+
+### Agent Harness
+
+The Agent Swarm Harness is compulsory for coding agents. See `docs/agents/agent-harness.md`.

CONTEXT.md

@@ -0,0 +1,113 @@
+# An Adventure in Thousand Token Wood — Project Context
+
+Build Small Hackathon 2026, Track 2. A sub-32B agent swarm that builds software
+in sandboxes. One prompt in, a working codebase out.
+
+## Language
+
+**Run**:
+One execution started from a user's prompt. A Run owns the prompt, task plan,
+event stream, codebase archive, validation report, and final summary.
+
+**Swarm**:
+The agent organization that works on a Run. One DeepAgent with five subagents
+(Planner, Coder, Reviewer, Test-runner, Validator-prep).
+
+**Coordinator**:
+The main agent inside the Swarm. Interprets the prompt, plans tasks, delegates
+to subagents, and decides when the Run is ready for validation.
+
+**Codebase**:
+The file-based deliverable produced by a Run, downloadable as a zip archive.
+
+**Workspace**:
+The sandbox filesystem where the Swarm creates the Codebase. Separate from
+the Validator sandbox.
+
+**Codebase archive**:
+A durable snapshot of the Codebase used for downloads and validation.
+
+**Codebase handoff**:
+The module that moves a Codebase from a Swarm Workspace into a Codebase archive
+and restores that archive into the Validator sandbox.
+
+**Validator**:
+The LangGraph workflow that restores a Codebase archive into a clean sandbox,
+runs validation checks, performs rubric review, and produces a pass/fail report.
+
+**Validator plan**:
+A typed plan of command checks and Stagehand checks that the Validator graph
+executes. User tests and generated Validation checks are converted into this
+plan before validation starts.
+
+**Model provider**:
+The model backend selected for a Run. Supported choices include OpenRouter,
+Gemini, Nebius, Hugging Face Router, custom OpenAI-compatible endpoints, and
+local OpenAI-compatible endpoints. User-supplied API keys are live-session
+credentials only and are not persisted. Model lists may be cached briefly in
+process memory and reset when the user refreshes models.
+
+**Model catalog**:
+The normalized list of models available from a Model provider. Provider-specific
+catalog responses are converted into one internal schema and cached briefly.
+Only fetched models whose provider ID or label proves `<=32B` parameters are
+eligible for Run selection; unknown-size models remain visible in catalog
+responses but must not be selectable.
+
+**Demo template**:
+A Backyard Demo Builder preset containing prompt, usefulness criteria, and demo
+checks. The first template is the Real Estate Follow-up CRM for a real-estate
+agent testing customer reminders before paying for full software.
+
+**Field notes**:
+Submission evidence generated from a Run. Field notes summarize the real
+person, hypothesis, tasks, events, validation checks, and feedback questions.
+
+**Validator graph**:
+The LangGraph workflow: run_validation_checks → run_stagehand_checks →
+rubric_review → finalize_report.
+
+**Event stream**:
+The ordered, user-visible history of a Run: planning, task progress, subagent
+work, artifact creation, validation, and final summary. Surfaces on the Gradio
+UI Events panel.
+
+**Rejoin token**:
+A server-issued secret that lets the user reconnect to a Run after page refresh
+or server restart.
+
+**Thread inspector**:
+The debug-only module for ad-hoc AgentSession creation, messages, and sandbox
+file inspection. Separate from the prompt-first Run workbench.
+
+## Flagged Ambiguities
+
+**Swarm runtime shape**:
+For the hackathon, Swarm = one DeepAgent with multiple subagents. Not multiple
+independent agent runtimes.
+
+**Validator sandbox**:
+Separate from the worker Workspace — the Validator starts from the archived
+codebase, not from the live workspace.
+
+## Hackathon Specifics
+
+- **Model**: User-selected fetched provider model whose fetched metadata proves `<=32B`.
+- **API keys**: Public Gradio runs require the user to enter their own hosted-provider key; server fallback keys are for trusted server/CLI paths only.
+- **UI**: Custom dark-themed Gradio with Off-Brand styling bonus badge
+- **Bonus badges**: Off-Brand, Sharing is Caring, Field Notes
+- **Track**: Chapter 1 Backyard AI — build small, real-person, <=32B demo
+
+## Example Dialogue
+
+User: "Build me a small FastAPI app with tests."
+
+Coordinator: "I created a Run, planned backend/tests/packaging tasks, delegated
+to coding and review subagents."
+
+Validator: "I restored the Codebase archive into a clean sandbox and ran the
+generated checks from your criteria. All passed."
+
+User: "Can I download it?"
+
+Coordinator: "Yes. Here's your codebase.zip with 5 files and passing tests."

Dockerfile

@@ -0,0 +1,32 @@
+FROM python:3.11-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    GRADIO_SERVER_NAME=0.0.0.0 \
+    GRADIO_SERVER_PORT=7860 \
+    PATH="/app/.venv/bin:${PATH}" \
+    UV_LINK_MODE=copy
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/astral-sh/uv:0.6.4 /uv /uvx /bin/
+
+WORKDIR /app
+
+RUN uv venv .venv
+
+COPY requirements.txt pyproject.toml ./
+RUN uv pip install --no-cache -r requirements.txt
+
+COPY app.py ./
+COPY arena/ ./arena/
+COPY skills/ ./skills/
+
+EXPOSE 7860
+
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+    CMD curl -fsS http://localhost:7860/health || exit 1
+
+CMD ["python", "app.py"]

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Filip Brebera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,30 @@
+.PHONY: dev gradio test smoke validator-smoke judge-smoke daytona-validator-smoke daytona-judge-smoke clean
+
+TASK := python scripts/task.py
+
+dev:
+	$(TASK) dev
+
+gradio:
+	$(TASK) gradio
+
+test:
+	$(TASK) test
+
+smoke:
+	$(TASK) smoke
+
+validator-smoke:
+	$(TASK) validator-smoke
+
+judge-smoke:
+	$(TASK) judge-smoke
+
+daytona-validator-smoke:
+	$(TASK) daytona-validator-smoke
+
+daytona-judge-smoke:
+	$(TASK) daytona-judge-smoke
+
+clean:
+	$(TASK) clean

README.md

@@ -1,13 +1,247 @@
 ---
-title: Agent Swarm Workbench
-emoji: 🐠
-colorFrom: green
+title: Backyard Demo Builder
+emoji: 🏡
+colorFrom: gray
 colorTo: green
 sdk: gradio
-sdk_version: 6.16.0
-python_version: '3.13'
+python_version: "3.12.12"
 app_file: app.py
+short_description: Build tiny real-person demos before scaling custom software.
+models:
+  - unsloth/gemma-4-12B-it-qat-GGUF
+  - Qwen/Qwen2.5-7B-Instruct
+  - nvidia/Nemotron-3.5-Content-Safety
+datasets: []
+tags:
+  - build-small-hackathon
+  - backyard-ai
+  - gradio
+  - agents
+  - small-language-model
+  - demo-builder
+  - real-estate
+  - ai-agents
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Backyard Demo Builder
+
+## Chapter 1: Backyard AI
+
+*Build Small Hackathon 2026 — Chapter 1 Submission*
+
+`agent-swarm-workbench` now presents as **Backyard Demo Builder**: a Gradio app
+that turns one real person's workflow into a small runnable demo package before
+anyone pays to build full software.
+
+First backyard case: my mom, a real-estate agent. She needs a cheap way to test
+a customer follow-up reminder workflow before committing time and money to a
+full app.
+
+---
+
+## Watch the Demo Builder Work
+
+```
+You:     "Build a real-estate follow-up CRM demo for my mom."
+Builder: Generates a Gradio mini-app, handoff spec, field notes, and checks
+Result:  app.py, README.md, handoff_spec.md, field_notes.md
+Mom:     Tests the workflow, then we scrap or scale.
+```
+
+Every Run produces a **downloadable demo package** and Validation report: files
+you can inspect, unzip, run, and test with the real person.
+
+---
+
+## Build Small Hackathon — Submission Notes
+
+| Requirement | How We Meet It |
+|---|---|
+| **Small model (≤ 32B)** | Provider catalog fetches models at runtime and only allows models whose ID/name proves ≤32B |
+| **Gradio app** | Custom dark-themed Gradio UI mounted on FastAPI |
+| **HF Space** | `app.py` + `requirements.txt` — one-command deploy |
+| **Demo video** | *(placeholder — [link to demo])* |
+| **Social post** | *(placeholder — [link to post])* |
+
+### Bonus Badges Claimed
+
+| Badge | Why |
+|---|---|
+| **🎨 Off-Brand** | Fully custom CSS dark theme — Archivo + IBM Plex Mono, acid green CTAs, paper/ink palette, CSS grid layout, status chips. Not a default Gradio component in sight. |
+| **📡 Sharing is Caring** | Agent traces and swarm reasoning are surfaced in the Events panel. We'll publish a trace on the Hub. |
+| **📓 Field Notes** | Generated demo packages include `field_notes.md`; this repo also documents the architecture and decisions. |
+
+---
+
+## Why This Belongs in Backyard AI
+
+This solves a real problem for someone I know.
+
+- **Specific person** — my mom, a real-estate agent.
+- **Specific pain** — follow-up reminders and customer-care demos are useful, but custom app dev is slow and risky.
+- **Honest small-model fit** — a ≤32B model drafts the demo and handoff spec; rules handle the reminder logic.
+- **Actually testable** — the generated package includes field notes and feedback questions for the real user.
+
+---
+
+## How It Works Under the Hood
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Gradio UI / HTTP API                               │
+├─────────────────────────────────────────────────────┤
+│  RunFlow — lifecycle conductor                      │
+│  ┌──────────┐  ┌────────────┐  ┌────────────────┐  │
+│  │ Swarm    │  │ Codebase   │  │ Validator      │  │
+│  │ Runtime  │→│ Archive    │→│ Graph          │  │
+│  │          │  │ Store      │  │                │  │
+│  │ Planner  │  │ (local/    │  │ Sandbox checks │  │
+│  │ Coder    │  │  Redis)    │  │ Rubric review  │  │
+│  │ Reviewer │  │            │  │ Stagehand      │  │
+│  │ Tester   │  │            │  │ (Browserbase)  │  │
+│  └──────────┘  └────────────┘  └────────────────┘  │
+│  EventBus → SSE stream to UI                       │
+└─────────────────────────────────────────────────────┘
+```
+
+### The Swarm
+
+- **Coordinator** reads the prompt, plans tasks, delegates to subagents
+- **Planner** breaks down the prompt into implementable units
+- **Coder** writes the actual code files
+- **Reviewer** checks code quality and correctness
+- **Test-runner** runs the user's tests and retries up to 3x on failure
+- **Validator-prep** generates validation checks from user criteria
+
+### The Validator
+
+After the swarm finishes, a LangGraph Validator workflow:
+1. Restores the codebase into a clean sandbox
+2. Runs user-provided tests
+3. Executes LLM-based rubric review
+4. (Optional) Runs Browserbase/Stagehand visual checks
+5. Produces a pass/fail Validation Report
+
+### The Sandbox
+
+All agent work happens inside isolated sandbox workspaces:
+- **Local** (for dev/smoke tests)
+- **Docker** (container-based)
+- **Daytona** (cloud sandboxes)
+
+---
+
+## Run It
+
+```bash
+git clone https://github.com/Kiy-K/agent-swarm-workbench.git
+cd agent-swarm-workbench
+cp .env.example .env
+# Optional: add server fallback keys. Users can also paste their own key in the UI.
+uv run uvicorn app:app --host 0.0.0.0 --port 8790
+```
+
+Open http://localhost:8790, type a prompt, choose a provider, fetch models with your API key, then click Start Run.
+
+Model selection:
+- Model lists are fetched from the selected provider/API endpoint at runtime.
+- UI only offers fetched models whose ID/name proves `<=32B` parameters.
+- Unknown-size models are shown in the catalog response as `unknown_parameters` but are not selectable.
+- User API keys and fetched catalogs live only in process memory. They are not persisted, not stored in Redis/DB, and not kept in Gradio state. Click "Refresh models" to clear and refetch that provider cache.
+
+For Hugging Face Spaces:
+```bash
+uv run python app.py
+```
+
+## Test
+
+```bash
+python scripts/task.py verify    # required completion gate: tests + harness
+python scripts/task.py test      # 90 tests, all passing
+python scripts/task.py harness -- --prompt "Build a tiny CLI" --test "test -f README.md"
+python scripts/task.py smoke      # Local agent session smoke check
+python scripts/task.py validator-smoke  # Validator end-to-end
+```
+
+### Agent Harness
+
+The harness is the fast way to exercise the Run lifecycle without waiting on a
+full demo session:
+
+```bash
+python scripts/task.py verify
+python scripts/task.py harness -- --prompt "Build a tiny CLI" --output-dir /tmp/harness
+python scripts/task.py harness -- --mode live --prompt "Build a tiny CLI"
+```
+
+`verify` is the required completion gate for coding agents. It runs the Python
+suite, then runs the default scripted Agent Swarm Harness so changes are checked
+against the same Run -> SwarmRuntime -> Archive -> Validator path that the app
+uses.
+
+Modes:
+
+| Mode | Purpose |
+|---|---|
+| `swarm` | Default. Runs `RunFlow -> SwarmRuntime -> Archive -> Validator` with a scripted local DeepAgent-compatible session. |
+| `live` | Uses the real `create_session()` DeepAgents path and the configured sandbox provider. |
+
+## Environment
+
+| Var | Purpose |
+|---|---|
+| `DEEPAGENT_MODEL_PROVIDER` | Server fallback model provider: `openrouter`, `gemini`, `nebius`, `huggingface`, `custom`, or `local` |
+| `DEEPAGENT_MODEL` | Server fallback model ID. Must prove `<=32B` when selected per Run. |
+| `DEEPAGENT_MODEL_BASE_URL` | Optional OpenAI-compatible `/v1` endpoint |
+| `OPENROUTER_API_KEY` / `GEMINI_API_KEY` / `NEBIUS_API_KEY` / `HF_TOKEN` | Optional server fallback keys for trusted server/CLI runs only. The public Gradio UI requires the user to enter their own hosted-provider key and does not use these by default. |
+| `DEEPAGENT_SANDBOX_PROVIDER` | `local`, `docker`, or `daytona` |
+| `BROWSERBASE_API_KEY` | Optional — visual validation via Stagehand |
+| `UPSTASH_REDIS_REST_URL` / `TOKEN` | Optional — persistent runs & archives |
+
+---
+
+## Stack
+
+- **Python 3.11+** / **FastAPI** / **Gradio 6**
+- **LangChain DeepAgents** — multi-subagent swarm runtime
+- **Provider adapters** — OpenRouter, Gemini, Nebius, Hugging Face Router, custom OpenAI-compatible, local OpenAI-compatible
+- **LangGraph** — Validator workflow
+- **QuickJS code interpreter** — in-sandbox code execution middleware
+- **Browserbase + Stagehand** — visual web validation (optional)
+
+## Architecture
+
+```
+arena/
+  agent.py           — Swarm factory, model, subagents, sandbox backend
+  backyard_templates.py — Backyard demo template registry
+  model_provider.py  — Chat model factory for provider selection
+  model_catalog.py   — Provider model list adapters and TTL cache
+  swarm_runtime.py   — Active Run registration and Swarm session leasing
+  swarm_session.py   — Prompt seeding, agent turns, test retries, snapshots
+  sandbox_lease.py   — Idle TTL, touch, and close behavior for sandboxes
+  run_flow.py        — Run lifecycle: create → execute → archive → validate
+  run_journal.py     — Run mutation journal: status, tasks, events, timestamps
+  run_store.py       — Run persistence (InMemory / Redis via Upstash)
+  codebase_handoff.py — Workspace snapshot and Validator sandbox restore
+  codebase_archive.py — Archive persistence (local / Redis)
+  validator_plan.py  — Typed Validator plan from user tests/checks
+  validator_graph.py — LangGraph Validator workflow
+  thread_inspector.py — Manual Thread/session debug surface
+  gradio_app.py      — Thin Gradio component wiring
+  gradio_presenter.py — Run output formatting for Gradio
+  gradio_markup.py   — Static Gradio shell markup
+  api.py             — FastAPI REST + SSE endpoints
+  event_bus.py       — In-process event streaming
+  browserbase_tools.py  — Web fetch/search tools for the swarm
+  stagehand_validator.py — Browserbase visual validation
+  docker_backend.py  — Docker sandbox provider
+  skill_catalog.py   — Bundled DeepAgents skills discovery
+tests_python/        — Python test suite (integration + unit)
+```
+
+---
+
+*Built with a sub-32B model for the Build Small Hackathon, June 2026.*

ROADMAP.md

@@ -0,0 +1,280 @@
+# ROADMAP
+
+## Goal
+
+Build Agent Swarm Workbench: a prompt-first agent swarm workbench for Hugging Face Spaces.
+
+The user provides one prompt for a codebase. The system creates a persisted Run, uses one DeepAgent with multiple subagents to plan and build the codebase, archives the result as a downloadable zip, restores that archive into a clean Validator sandbox, runs generated validation checks, and returns a summary with changed files and a Validation report.
+
+## Locked Product Decisions
+
+- The deliverable is a **Codebase**.
+- The user can download the Codebase as a `.zip`.
+- The MVP Swarm is **one DeepAgent with multiple subagents**.
+- The Coordinator generates validation checks from the prompt and user Criteria.
+- User-defined tests or Criteria are first-class inputs.
+- Validation is mandatory before a Run can be considered complete.
+- Validation runs in a separate **Validator sandbox**, never in the live worker Workspace.
+- The final output is Summary + changed files + Validation report + Codebase zip.
+- Keep the Python package name `arena` for now; the repo and public product name are `agent-swarm-workbench` / Agent Swarm Workbench.
+
+## Architecture Ground Rules
+
+- Keep FastAPI and Gradio thin over `ArenaService`.
+- Keep DeepAgent construction behind `create_session()`.
+- Keep the Swarm runtime behind a small module interface.
+- Keep persistence behind small store interfaces.
+- Keep archive persistence behind the Codebase archive seam.
+- Keep validation orchestration in LangGraph.
+- Keep the worker Workspace and Validator sandbox separate.
+- Preserve a runnable app after every phase.
+- New product work must use Run, Swarm, Task, Codebase, Criteria, Validator, and Validation report language.
+- Legacy Match, Host, Participant, Challenge, Leaderboard, Judge, and Score language is quarantined outside the active app path.
+
+## Current Assets To Reuse
+
+- Python/FastAPI/Gradio app shell.
+- `ArenaService` application seam.
+- DeepAgents session factory and subagent support.
+- Local and Daytona sandbox adapters.
+- Upstash Redis REST client and store patterns.
+- Local and Redis-backed archive storage.
+- Sandboxed command executor used by the Validator.
+- Repo skill catalog mounted at `/skills/`.
+
+## Current Refactor Status
+
+All nine phases are complete. The project is now Agent Swarm Workbench.
+
+- `arena/run_flow.py` owns the prompt-first Run lifecycle.
+- `arena/codebase_archive.py` is the only Codebase archive seam.
+- `arena/validator_executor.py` exposes a Validator-named sandbox adapter and factory.
+- `arena/gradio_app.py` is prompt-first only: prompt, Criteria, user tests, Run status, task table, event table, Validation report, and Codebase zip link.
+- `arena/agent.py` keeps DeepAgents as the Swarm SDK with subagents and tool interrupts.
+- `arena/api.py` and `arena/service.py` expose Run, skills, archive download, event streaming, and Validator operations.
+- `arena/run_models.py` and `arena/validation_models.py` provide prompt-first import surfaces; `arena/models.py` contains only active Run/Validator models.
+- `arena/redis_client.py` is the only source of `RedisClient`, `UpstashRedisRestClient`, and `RedisStoreError`.
+- Legacy `match_store.py`, `match_flow.py`, `vibecoder.py`, and `judge_graph.py` are deleted.
+- Package name `arena` kept.
+
+## MVP Success Criteria
+
+1. User starts a Run from one prompt and optional Criteria.
+2. Run receives a hidden rejoin token and survives refresh.
+3. One DeepAgent Swarm creates a task plan and works through subagents.
+4. Event stream shows plan, task progress, artifact creation, validation, and final summary.
+5. The Swarm produces a Codebase archive.
+6. The Codebase archive is downloadable as a zip.
+7. Validator graph restores the Codebase archive into a clean Validator sandbox.
+8. Validator runs generated checks and user-defined tests/Criteria-derived checks.
+9. Final response includes summary, changed files, Validation report, and risks.
+10. Redis-backed Run records and Codebase archives survive process restart.
+
+## Phase 1: Run Domain Models
+
+Purpose: introduce the new domain language in code without broad renames.
+
+Add models:
+
+- `Run`
+- `RunRequest`
+- `RunView`
+- `RunStatus`
+- `RunTask`
+- `TaskStatus`
+- `RunArtifact`
+- `RunEvent`
+- `Criteria`
+- `ValidationCheck`
+- `ValidationCheckResult`
+- `ValidationReport`
+- `CodebaseArchive`
+
+Done when:
+
+- Tests validate Run creation, task state, event ordering, artifact pointers, Criteria, and Validation report shape.
+- Legacy match models still pass while migration continues.
+
+## Phase 2: Run Store
+
+Purpose: persist prompt-first Runs behind a real seam.
+
+Adapters:
+
+- `InMemoryRunStore`
+- `RedisRunStore`
+
+Behavior:
+
+- Create Run from prompt and Criteria.
+- Issue Rejoin token.
+- Load public Run view without exposing secrets.
+- Rejoin by token.
+- Append Run events.
+- Save task state.
+- Save Codebase archive pointer.
+- Save Validation checks and Validation report.
+- Restore after process restart.
+- Mark active tasks interrupted if their runtime is gone.
+
+Done when:
+
+- Fake Redis tests cover create, rejoin, event append, task update, artifact update, validation update, and restart recovery.
+
+## Phase 3: DeepAgent Swarm Runtime
+
+Purpose: express the MVP Swarm as one DeepAgent with multiple subagents.
+
+Subagents:
+
+- planner
+- coder
+- reviewer
+- test-runner
+- validator-prep
+
+Behavior:
+
+- Seed User prompt and Criteria as read-only context.
+- Work inside `/workspace`.
+- Stream normalized events.
+- Record changed files.
+- Produce a Codebase archive through the archive seam.
+- Return a summary of work and known risks.
+
+Done when:
+
+- One local fake Run can execute through the Swarm runtime and produce a Codebase archive.
+- Legacy runner concepts are replaced by `SwarmRuntime`.
+
+## Phase 4: Codebase Archive And Zip Download
+
+Purpose: make the Codebase a durable, downloadable artifact.
+
+Behavior:
+
+- Archive all files from `/workspace`.
+- Persist archive locally or in Redis depending on provider.
+- Generate a `.zip` from the archived Codebase.
+- Expose zip download through Gradio and FastAPI.
+- Keep file size caps and path validation.
+
+Done when:
+
+- A Run produces a zip after completion.
+- Zip generation works after process restart from Redis archive.
+
+## Phase 5: Validator Graph
+
+Purpose: retarget judge sandbox machinery into mandatory validation under Validator-named seams.
+
+Files:
+
+- `arena/validator_graph.py`
+- `arena/validator_executor.py`
+- `arena/codebase_handoff.py`
+- `arena/codebase_executor.py`
+
+Behavior:
+
+1. Restore Codebase archive into a clean Validator sandbox.
+2. Run all generated Validation checks.
+3. Run user-defined tests when provided.
+4. Optionally run LLM review over prompt, Criteria, changed files, and command outputs.
+5. Produce a Validation report.
+6. Attach the Validation report to the Run.
+
+Status: done for the active app path.
+
+Note: the old Judge executor alias has been removed. Validator restore now goes through the Codebase handoff module.
+
+Done when:
+
+- Primary service path is `validate_run()`.
+- Judge language is not exposed by FastAPI or Gradio.
+
+## Phase 6: Swarm Flow
+
+Purpose: replace Match lifecycle with prompt-to-codebase Run orchestration.
+
+Behavior:
+
+- Start Run.
+- Ask Coordinator to plan tasks.
+- Execute one DeepAgent Swarm runtime.
+- Persist events and task updates.
+- Archive Codebase.
+- Run Validator.
+- Mark Run completed only after mandatory validation.
+
+Done when:
+
+- A Run can complete end-to-end in local fake mode.
+- Restart keeps archived Codebase and Validation report.
+- Active work lost after restart becomes interrupted.
+
+## Phase 7: Prompt-First Gradio UI
+
+Purpose: remove competition controls from the user-facing app.
+
+Status: done for the Hackathon demo shell. Legacy Match/Judge controls are no longer exposed in Gradio.
+
+UI:
+
+- Prompt input.
+- Optional Criteria/tests input.
+- Start Run.
+- Rejoin token.
+- Event stream.
+- Task table.
+- Changed files.
+- Validation report.
+- Zip download.
+- Final summary.
+
+Remove from primary UI:
+
+- Host tab.
+- Join tab.
+- Match code.
+- Participant controls.
+- Leaderboard.
+
+Done when:
+
+- User can run the full workflow without touching internal IDs.
+
+## Phase 8: Run API
+
+Purpose: expose prompt-first endpoints.
+
+Primary endpoints (current):
+
+- `POST /runs`
+- `GET /runs/{run_id}`
+- `POST /runs/rejoin`
+- `POST /runs/{run_id}/validate`
+- `GET /runs/{run_id}/codebase.zip`
+
+Streaming endpoint:
+
+- `GET /runs/{run_id}/events` for streamed Run events.
+
+Done when:
+
+- FastAPI tests cover prompt-first Run lifecycle.
+- Legacy match endpoints are not exposed by the active FastAPI app.
+
+## Phase 9: Product Rename Cleanup
+
+Purpose: delete or quarantine old arena language after behavior is migrated.
+
+Status: done for the public product and repository name.
+
+Done when:
+
+- UI title, README, ROADMAP, CONTEXT, AGENTS, and tests use swarm/run language.
+- Legacy match modules are deleted.
+- No active-path module under `arena/` imports from `arena/match_store.py`, `arena/match_flow.py`, `arena/vibecoder.py`, or `arena/judge_graph.py`.
+- `python scripts/task.py test` passes after the cleanup.
+- Python package name `arena` kept.

app.py

@@ -0,0 +1,76 @@
+"""Unified ASGI entrypoint for API and Gradio UI."""
+
+from __future__ import annotations
+
+import os
+
+import gradio as gr
+import uvicorn
+
+from arena.api import app as fastapi_app
+from arena.api import service
+from arena.gradio_app import build_app
+
+
+demo = build_app(service)
+
+
+def create_app():
+    """Create one FastAPI ASGI app with Gradio mounted at the root."""
+
+    return gr.mount_gradio_app(fastapi_app, demo, path="/")
+
+
+app = create_app()
+
+
+try:
+    import spaces
+except Exception:
+    class _SpacesShim:
+        def GPU(self, fn=None, **kwargs):
+            del kwargs
+
+            def decorator(inner):
+                return inner
+
+            return decorator(fn) if fn else decorator
+
+    spaces = _SpacesShim()
+
+
+@spaces.GPU
+def zerogpu_ready_marker() -> str:
+    return "ready"
+
+
+def server_config() -> dict[str, int | str]:
+    host = os.getenv("GRADIO_SERVER_NAME", os.getenv("HOST", "0.0.0.0"))
+    port = int(os.getenv("GRADIO_SERVER_PORT") or os.getenv("PORT") or "7860")
+    return {"host": host, "port": port}
+
+
+def gradio_launch_config() -> dict[str, int | str]:
+    config = server_config()
+    return {"server_name": str(config["host"]), "server_port": int(config["port"])}
+
+
+def should_launch_gradio_space() -> bool:
+    return bool(os.getenv("SPACE_ID")) and os.getenv("FORCE_SELF_LAUNCH") != "1"
+
+
+def should_self_launch() -> bool:
+    if os.getenv("FORCE_SELF_LAUNCH") == "1":
+        return True
+    return not should_launch_gradio_space()
+
+
+def _space_sdk() -> str:
+    return os.getenv("SPACE_SDK", os.getenv("HF_SPACE_SDK", "")).strip().lower()
+
+
+if __name__ == "__main__":
+    if should_launch_gradio_space():
+        demo.launch(**gradio_launch_config())
+    elif should_self_launch():
+        uvicorn.run(app, **server_config())

arena/__init__.py

@@ -0,0 +1 @@
+"""Backyard Demo Builder package."""

arena/agent.py

@@ -0,0 +1,281 @@
+"""DeepAgent factory plus sandbox lifecycle."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from deepagents import create_deep_agent
+from deepagents.backends import CompositeBackend, FilesystemBackend, LocalShellBackend
+from deepagents.middleware.filesystem import FilesystemPermission
+from deepagents.middleware.summarization import create_summarization_tool_middleware
+from langchain_quickjs import CodeInterpreterMiddleware
+from langgraph.checkpoint.memory import MemorySaver
+
+from .model_catalog import ModelProviderConfig
+from .model_provider import create_chat_model, normalize_openrouter_model
+from .paths import SKILLS_ROOT
+
+
+DEFAULT_PROVIDER = "daytona"
+DOTENV_PATH = Path(".env")
+APPROVAL_TOOL_NAMES = ("execute", "write_file", "edit_file")
+
+
+SYSTEM_PROMPT = """You are an agent swarm workbench Coordinator.
+
+Goal:
+- Build complete codebases from a user's prompt inside the sandbox filesystem.
+- Start every non-trivial run by using the planning/todo tool.
+- Keep Run context and Criteria in files, then read only what is needed.
+- Use sandbox tools to write files, run checks, inspect failures, and improve output.
+- Use the interpreter for structured transforms, batching, or tool composition inside the agent loop.
+- Delegate isolated tasks to subagents when it keeps the main context focused.
+- Return concise progress plus final file paths changed.
+- Use browserbase_fetch to retrieve documentation, API refs, or reference content.
+- Use browserbase_search to find examples, docs, or verify approaches.
+
+Rules:
+- Work in sandbox only.
+- Treat /context as read-only source material and /workspace as the codebase workspace.
+- Prefer runnable, testable artifacts.
+- Run commands through sandbox execute tool.
+- Never claim code works unless you ran relevant command or explain why not.
+"""
+
+
+SUBAGENTS = [
+    {
+        "name": "planner",
+        "description": "Turns the User prompt and Criteria into ordered implementation tasks.",
+        "system_prompt": "Create concise, dependency-aware task plans for the codebase.",
+    },
+    {
+        "name": "coder",
+        "description": "Implements codebase files in /workspace.",
+        "system_prompt": "Create clean, runnable code. Keep files focused and cohesive.",
+    },
+    {
+        "name": "reviewer",
+        "description": "Reviews codebase changes against the prompt and Criteria.",
+        "system_prompt": "Find correctness, maintainability, and completeness gaps.",
+    },
+    {
+        "name": "test-runner",
+        "description": "Runs workspace commands and diagnoses failures.",
+        "system_prompt": "Run checks, summarize failing command, propose minimal fix.",
+    },
+    {
+        "name": "validator-prep",
+        "description": "Prepares validation checks from User prompt and Criteria.",
+        "system_prompt": "Convert expected behavior into concrete validation commands and risks.",
+    },
+]
+
+
+def _load_dotenv(path: Path = DOTENV_PATH) -> None:
+    if not path.exists():
+        return
+    for raw_line in path.read_text().splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        value = value.strip().strip("\"'")
+        if key and key not in os.environ:
+            os.environ[key] = value
+
+
+@dataclass
+class AgentSession:
+    thread_id: str
+    provider: str
+    backend: Any
+    agent: Any
+    workspace_dir: str = "/workspace"
+    sandbox: Any | None = None
+    context_root: Path | None = None
+    checkpointer: Any | None = None
+    messages: list[dict[str, str]] = field(default_factory=list)
+
+    def close(self) -> None:
+        if self.provider == "daytona" and self.sandbox is not None:
+            cleanup = getattr(self.sandbox, "delete", None) or getattr(self.sandbox, "stop", None)
+            if callable(cleanup):
+                cleanup()
+        if self.context_root is not None:
+            shutil.rmtree(self.context_root, ignore_errors=True)
+
+
+def _normalize_openrouter_model(model: str) -> str:
+    return normalize_openrouter_model(model)
+
+
+def _openrouter_model():
+    return create_chat_model()
+
+
+def _middleware(model: Any, backend: Any) -> list[Any]:
+    return [
+        CodeInterpreterMiddleware(skills_backend=backend),
+        create_summarization_tool_middleware(model, backend),
+    ]
+
+
+def _permissions() -> list[FilesystemPermission]:
+    return [
+        FilesystemPermission(operations=["write"], paths=["/context/**"], mode="deny"),
+        FilesystemPermission(operations=["write"], paths=["/skills/**"], mode="deny"),
+    ]
+
+
+def _context_backend(thread_id: str) -> tuple[FilesystemBackend, Path]:
+    root = Path(tempfile.gettempdir()) / "agent-swarm-workbench-context" / thread_id
+    root.mkdir(parents=True, exist_ok=True)
+    return FilesystemBackend(root_dir=root, virtual_mode=True), root
+
+
+def _skills_backend() -> FilesystemBackend:
+    SKILLS_ROOT.mkdir(parents=True, exist_ok=True)
+    return FilesystemBackend(root_dir=SKILLS_ROOT, virtual_mode=True)
+
+
+def _composite_backend(executable_backend: Any, thread_id: str) -> tuple[CompositeBackend, Path]:
+    context_backend, context_root = _context_backend(thread_id)
+    return (
+        CompositeBackend(
+            default=executable_backend,
+            routes={
+                "/context/": context_backend,
+                "/skills/": _skills_backend(),
+            },
+        ),
+        context_root,
+    )
+
+
+def _daytona_backend() -> tuple[Any, Any]:
+    from daytona import Daytona
+    from langchain_daytona import DaytonaSandbox
+
+    client = Daytona()
+    sandbox = client.create()
+    backend = DaytonaSandbox(sandbox=sandbox)
+    backend._daytona_client = client
+    backend._workspace_dir = "/home/daytona/workspace"
+    return backend, sandbox
+
+
+def _docker_backend() -> tuple[Any, Any]:
+    from .docker_backend import DockerSandboxBackend
+
+    image = os.getenv("DOCKER_SANDBOX_IMAGE", "python:3.11-slim")
+    backend = DockerSandboxBackend(image=image)
+    backend._workspace_dir = "/workspace"
+    return backend, backend
+
+
+def _local_backend(thread_id: str) -> tuple[Any, None]:
+    root = Path(tempfile.gettempdir()) / "agent-swarm-workbench-sandboxes" / thread_id
+    root.mkdir(parents=True, exist_ok=True)
+    backend = LocalShellBackend(root_dir=root, virtual_mode=True, inherit_env=True)
+    backend._workspace_dir = "/workspace"
+    return backend, None
+
+
+def _truthy_env(name: str) -> bool:
+    return os.getenv(name, "").lower() in {"1", "true", "yes", "on"}
+
+
+def _approval_tools() -> list[str]:
+    configured = os.getenv("DEEPAGENT_INTERRUPT_TOOLS", "").strip()
+    if configured:
+        requested = [item.strip() for item in configured.replace(";", ",").split(",") if item.strip()]
+        unknown = sorted(set(requested) - set(APPROVAL_TOOL_NAMES))
+        if unknown:
+            raise ValueError(f"Unsupported DeepAgent interrupt tools: {', '.join(unknown)}")
+        return requested
+    if _truthy_env("DEEPAGENT_REQUIRE_TOOL_APPROVAL"):
+        return list(APPROVAL_TOOL_NAMES)
+    if _truthy_env("DEEPAGENT_REQUIRE_EXECUTE_APPROVAL"):
+        return ["execute"]
+    return []
+
+
+def _interrupt_on() -> dict[str, Any]:
+    return {
+        tool_name: {"allowed_decisions": ["approve", "reject"]}
+        for tool_name in _approval_tools()
+    }
+
+
+def _swarm_tools() -> list:
+    if not os.environ.get("BROWSERBASE_API_KEY"):
+        return []
+    try:
+        from langchain_core.tools import tool as lc_tool
+        from .browserbase_tools import browserbase_fetch, browserbase_search
+    except ImportError:
+        return []
+
+    @lc_tool
+    def fetch_tool(url: str, allow_redirects: bool = False) -> str:
+        """Fetch and return the content of a web page. Use for documentation, APIs, or static pages."""
+        return browserbase_fetch(url=url, allow_redirects=allow_redirects)
+
+    @lc_tool
+    def search_tool(query: str, num_results: int = 5) -> str:
+        """Search the web and return structured results with title, URL, and description."""
+        return browserbase_search(query=query, num_results=num_results)
+
+    return [fetch_tool, search_tool]
+
+
+def create_session(thread_id: str | None = None, model_provider: ModelProviderConfig | None = None) -> AgentSession:
+    _load_dotenv()
+    thread_id = thread_id or uuid4().hex
+    provider = os.getenv("DEEPAGENT_SANDBOX_PROVIDER", DEFAULT_PROVIDER).lower()
+
+    if provider == "daytona":
+        executable_backend, sandbox = _daytona_backend()
+    elif provider == "docker":
+        executable_backend, sandbox = _docker_backend()
+    elif provider == "local":
+        executable_backend, sandbox = _local_backend(thread_id)
+    else:
+        raise ValueError(f"Unsupported sandbox provider: {provider}")
+
+    backend, context_root = _composite_backend(executable_backend, thread_id)
+    workspace_dir = getattr(executable_backend, "_workspace_dir", "/workspace")
+    backend._workspace_dir = workspace_dir
+    model = create_chat_model(model_provider)
+    checkpointer = MemorySaver()
+    agent = create_deep_agent(
+        model=model,
+        system_prompt=SYSTEM_PROMPT,
+        backend=backend,
+        middleware=_middleware(model, backend),
+        subagents=SUBAGENTS,
+        skills=["/skills/"],
+        tools=_swarm_tools(),
+        permissions=_permissions(),
+        interrupt_on=_interrupt_on(),
+        checkpointer=checkpointer,
+        name="agent-swarm-workbench",
+    )
+    return AgentSession(
+        thread_id=thread_id,
+        provider=provider,
+        backend=backend,
+        sandbox=sandbox,
+        agent=agent,
+        workspace_dir=workspace_dir,
+        context_root=context_root,
+        checkpointer=checkpointer,
+    )

arena/api.py

@@ -0,0 +1,291 @@
+"""FastAPI transport for the unified Arena service."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import AsyncIterator
+
+from fastapi import FastAPI, HTTPException, Query, Request, Response
+from pydantic import BaseModel, Field
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import JSONResponse, StreamingResponse
+
+from .model_catalog import ModelProviderConfig, ProviderModel
+from .run_models import RunRequest, RunView
+from .run_store import InvalidRunToken, RunNotFound
+from .validation_models import ValidationReport
+from .service import (
+    ArenaService,
+    FileAccessFailed,
+)
+from .skill_catalog import SkillInfo
+from .thread_inspector import (
+    AgentRunFailed,
+    FileEntry,
+    MessageResponse,
+    ThreadInspector,
+    ThreadNotFound,
+    ThreadResponse,
+)
+
+
+app = FastAPI(title="Backyard Demo Builder", version="0.1.0")
+service = ArenaService()
+thread_inspector = ThreadInspector()
+sessions = thread_inspector.sessions
+
+API_KEY = os.getenv("ARENA_API_KEY", "")
+
+
+class AuthMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        if request.url.path in ("/health",) or not API_KEY:
+            return await call_next(request)
+        auth = request.headers.get("Authorization", "")
+        expected = f"Bearer {API_KEY}"
+        if auth != expected:
+            return JSONResponse(
+                status_code=401,
+                content={"detail": "Unauthorized"},
+            )
+        return await call_next(request)
+
+
+if API_KEY:
+    app.add_middleware(AuthMiddleware)
+
+
+class MessageRequest(BaseModel):
+    content: str = Field(min_length=1)
+
+
+class RejoinRequest(BaseModel):
+    token: str = Field(min_length=1)
+
+
+class RunMessageRequest(BaseModel):
+    content: str = Field(min_length=1)
+
+
+@app.get("/health")
+async def health() -> dict[str, str]:
+    return service.health()
+
+
+@app.get("/skills")
+async def list_skills() -> list[SkillInfo]:
+    return service.list_skills()
+
+
+@app.post("/models/catalog")
+async def list_provider_models(req: ModelProviderConfig) -> list[ProviderModel]:
+    try:
+        return service.list_provider_models(req)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except Exception as exc:
+        raise HTTPException(status_code=502, detail="Could not fetch provider models") from exc
+
+
+@app.post("/models/catalog/refresh")
+async def refresh_provider_models(req: ModelProviderConfig) -> list[ProviderModel]:
+    try:
+        return service.refresh_provider_models(req)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except Exception as exc:
+        raise HTTPException(status_code=502, detail="Could not refresh provider models") from exc
+
+
+@app.post("/runs")
+async def create_run(req: RunRequest) -> RunView:
+    return service.create_run(req).run
+
+
+@app.post("/runs/start")
+async def start_run(req: RunRequest) -> RunView:
+    return service.start_run(req).run
+
+
+@app.get("/runs/{run_id}")
+async def get_run(run_id: str) -> RunView:
+    try:
+        return service.get_run(run_id)
+    except RunNotFound as exc:
+        raise HTTPException(status_code=404, detail="Run not found") from exc
+
+
+@app.get("/runs/{run_id}/events")
+async def stream_run_events(run_id: str) -> StreamingResponse:
+    try:
+        service.get_run(run_id)
+    except RunNotFound as exc:
+        raise HTTPException(status_code=404, detail="Run not found") from exc
+
+    async def event_generator() -> AsyncIterator[str]:
+        import asyncio
+        q = service.subscribe_events(run_id)
+        loop = asyncio.get_event_loop()
+        while True:
+            event = await loop.run_in_executor(None, q.get)
+            if event is None:
+                break
+            yield f"data: {json.dumps(event, default=str)}\n\n"
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+@app.get("/runs/{run_id}/codebase.zip")
+async def get_run_codebase_zip(run_id: str) -> Response:
+    try:
+        payload = service.get_run_codebase_zip(run_id)
+    except RunNotFound as exc:
+        raise HTTPException(status_code=404, detail="Run not found") from exc
+    except FileAccessFailed as exc:
+        raise HTTPException(status_code=409, detail="Run has no codebase archive") from exc
+    return Response(
+        content=payload.data,
+        media_type=payload.content_type,
+        headers={"Content-Disposition": f'attachment; filename="{payload.filename}"'},
+    )
+
+
+@app.get("/runs/{run_id}/field_notes.md")
+async def get_run_field_notes(run_id: str) -> Response:
+    try:
+        payload = service.get_run_field_notes(run_id)
+    except RunNotFound as exc:
+        raise HTTPException(status_code=404, detail="Run not found") from exc
+    return Response(
+        content=payload.data,
+        media_type=payload.content_type,
+        headers={"Content-Disposition": f'attachment; filename="{payload.filename}"'},
+    )
+
+
+@app.get("/runs/{run_id}/trace.json")
+async def get_run_trace_json(run_id: str) -> Response:
+    try:
+        payload = service.get_run_trace_json(run_id)
+    except RunNotFound as exc:
+        raise HTTPException(status_code=404, detail="Run not found") from exc
+    return Response(
+        content=payload.data,
+        media_type=payload.content_type,
+        headers={"Content-Disposition": f'attachment; filename="{payload.filename}"'},
+    )
+
+
+@app.get("/runs/{run_id}/submission.md")
+async def get_run_submission_markdown(run_id: str) -> Response:
+    try:
+        payload = service.get_run_submission_markdown(run_id)
+    except RunNotFound as exc:
+        raise HTTPException(status_code=404, detail="Run not found") from exc
+    return Response(
+        content=payload.data,
+        media_type=payload.content_type,
+        headers={"Content-Disposition": f'attachment; filename="{payload.filename}"'},
+    )
+
+
+@app.get("/runs/{run_id}/space_README.md")
+async def get_run_space_readme(run_id: str) -> Response:
+    try:
+        payload = service.get_run_space_readme(run_id)
+    except RunNotFound as exc:
+        raise HTTPException(status_code=404, detail="Run not found") from exc
+    return Response(
+        content=payload.data,
+        media_type=payload.content_type,
+        headers={"Content-Disposition": f'attachment; filename="{payload.filename}"'},
+    )
+
+
+@app.post("/runs/rejoin")
+async def rejoin_run(req: RejoinRequest) -> RunView:
+    try:
+        return service.rejoin_run(req.token).run
+    except InvalidRunToken as exc:
+        raise HTTPException(status_code=404, detail="Token not found") from exc
+
+
+@app.post("/runs/{run_id}/cancel")
+async def cancel_run(run_id: str) -> RunView:
+    try:
+        return service.cancel_run(run_id)
+    except RunNotFound as exc:
+        raise HTTPException(status_code=404, detail="Run not found") from exc
+
+
+@app.post("/runs/{run_id}/messages")
+async def add_run_message(run_id: str, req: RunMessageRequest) -> RunView:
+    try:
+        return service.add_run_message(run_id, req.content)
+    except RunNotFound as exc:
+        raise HTTPException(status_code=404, detail="Run not found") from exc
+
+
+@app.post("/runs/{run_id}/validate")
+async def validate_run(run_id: str) -> ValidationReport:
+    try:
+        return service.validate_run(run_id)
+    except RunNotFound as exc:
+        raise HTTPException(status_code=404, detail="Run not found") from exc
+    except FileAccessFailed as exc:
+        raise HTTPException(status_code=409, detail="Run has no codebase archive") from exc
+
+
+@app.post("/threads")
+async def create_thread() -> ThreadResponse:
+    try:
+        return thread_inspector.create_thread()
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail="Could not create agent session") from exc
+
+
+@app.post("/threads/{thread_id}/messages")
+async def send_message(thread_id: str, req: MessageRequest) -> MessageResponse:
+    try:
+        return thread_inspector.send_message(thread_id, req.content)
+    except ThreadNotFound as exc:
+        raise HTTPException(status_code=404, detail="Thread not found") from exc
+    except AgentRunFailed as exc:
+        raise HTTPException(status_code=502, detail="Agent run failed") from exc
+
+
+@app.get("/threads/{thread_id}/files")
+async def list_files(thread_id: str, path: str = Query("/")) -> list[FileEntry]:
+    try:
+        return thread_inspector.list_files(thread_id, path)
+    except ThreadNotFound as exc:
+        raise HTTPException(status_code=404, detail="Thread not found") from exc
+    except FileAccessFailed as exc:
+        raise HTTPException(status_code=400, detail="Could not list files") from exc
+
+
+@app.get("/threads/{thread_id}/files/content")
+async def read_file(thread_id: str, path: str) -> dict[str, str]:
+    try:
+        return thread_inspector.read_file(thread_id, path)
+    except ThreadNotFound as exc:
+        raise HTTPException(status_code=404, detail="Thread not found") from exc
+    except FileAccessFailed as exc:
+        raise HTTPException(status_code=400, detail="Could not read file") from exc
+
+
+@app.delete("/threads/{thread_id}")
+async def delete_thread(thread_id: str) -> dict[str, bool]:
+    try:
+        return thread_inspector.delete_thread(thread_id)
+    except ThreadNotFound as exc:
+        raise HTTPException(status_code=404, detail="Thread not found") from exc

arena/backyard_templates.py

@@ -0,0 +1,51 @@
+"""Backyard Demo Builder templates."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class DemoTemplate:
+    id: str
+    label: str
+    prompt: str
+    criteria: str
+    checks: str
+
+
+REAL_ESTATE_FOLLOWUP = DemoTemplate(
+    id="real_estate_followup_crm",
+    label="Real Estate Follow-up CRM",
+    prompt="""Build a small Gradio demo app for a real-estate agent who needs a cheap way to test a customer follow-up workflow before paying for full software.
+
+The app should manage buyer/renter leads, compute next follow-up reminders from lead status and last-contact date, generate English/Vietnamese follow-up message drafts, include sample leads, and export a handoff spec.
+
+Keep data session-only. No auth, no DB, no external messaging APIs.""",
+    criteria="""Works as a Gradio app
+Uses English/Vietnamese UI toggle
+Includes sample real-estate leads
+Computes next follow-up reminders
+Generates follow-up message drafts
+Exports handoff spec and field notes
+No DB or cloud storage required""",
+    checks="""python -m py_compile app.py
+test -f README.md
+test -f handoff_spec.md
+test -f field_notes.md""",
+)
+
+
+TEMPLATES = (REAL_ESTATE_FOLLOWUP,)
+DEFAULT_TEMPLATE_ID = REAL_ESTATE_FOLLOWUP.id
+
+
+def template_choices() -> list[str]:
+    return [template.label for template in TEMPLATES]
+
+
+def template_by_label(label: str) -> DemoTemplate:
+    for template in TEMPLATES:
+        if template.label == label or template.id == label:
+            return template
+    return REAL_ESTATE_FOLLOWUP

arena/browserbase_tools.py

@@ -0,0 +1,123 @@
+"""Browserbase Fetch and Search tools for the DeepAgent swarm."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+from browserbase import Browserbase
+
+
+def _client() -> Browserbase:
+    api_key = os.environ.get("BROWSERBASE_API_KEY", "")
+    if not api_key:
+        raise RuntimeError("BROWSERBASE_API_KEY is required for fetch/search tools")
+    return Browserbase(api_key=api_key)
+
+
+def browserbase_fetch(url: str, allow_redirects: bool = False) -> str:
+    """Fetch and return the content of a web page without a browser.
+
+    Use this to retrieve HTML, JSON, or text content from a URL.
+    Best for static pages or API endpoints that don't require JavaScript.
+
+    Args:
+        url: The URL to fetch.
+        allow_redirects: Whether to follow HTTP redirects (default False).
+
+    Returns:
+        The page content as a string, or an error message if the fetch fails.
+    """
+    try:
+        response = _client().fetch_api.create(url=url, allow_redirects=allow_redirects)
+        if hasattr(response, "content"):
+            content = response.content
+            if len(content) > 10000:
+                content = content[:10000] + "\n...[truncated]"
+            return str(content)
+        return str(response)
+    except Exception as exc:
+        return f"Fetch error: {exc}"
+
+
+def browserbase_search(query: str, num_results: int = 5) -> str:
+    """Search the web and return structured results without a browser.
+
+    Use this to find URLs, documentation, or reference material.
+    Returns title, URL, and description for each result.
+
+    Args:
+        query: The search query string.
+        num_results: Number of results to return (1-25, default 5).
+
+    Returns:
+        Formatted JSON string with search results, or an error message.
+    """
+    try:
+        response = _client().search_api.create(query=query, num_results=num_results)
+        if hasattr(response, "results"):
+            formatted = []
+            for r in response.results:
+                entry = {}
+                if hasattr(r, "title"):
+                    entry["title"] = r.title
+                if hasattr(r, "url"):
+                    entry["url"] = r.url
+                if hasattr(r, "description"):
+                    entry["description"] = r.description
+                formatted.append(entry)
+            return json.dumps(formatted, indent=2, ensure_ascii=False)
+        return str(response)
+    except Exception as exc:
+        return f"Search error: {exc}"
+
+
+def _fetch_tool_schema() -> dict[str, Any]:
+    return {
+        "name": "browserbase_fetch",
+        "description": "Fetch and return the content of a web page without a browser. Use for static pages or APIs.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "url": {
+                    "type": "string",
+                    "description": "The URL to fetch.",
+                },
+                "allow_redirects": {
+                    "type": "boolean",
+                    "description": "Whether to follow HTTP redirects (default False).",
+                },
+            },
+            "required": ["url"],
+        },
+    }
+
+
+def _search_tool_schema() -> dict[str, Any]:
+    return {
+        "name": "browserbase_search",
+        "description": "Search the web for documentation, references, or examples. Returns title, URL, and description.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "The search query string.",
+                },
+                "num_results": {
+                    "type": "integer",
+                    "description": "Number of results to return (1-25, default 5).",
+                },
+            },
+            "required": ["query"],
+        },
+    }
+
+
+SWARM_TOOL_SCHEMAS: list[dict[str, Any]] = [_fetch_tool_schema(), _search_tool_schema()]
+
+SWARM_TOOLS: dict[str, Any] = {
+    "browserbase_fetch": browserbase_fetch,
+    "browserbase_search": browserbase_search,
+}

arena/codebase_archive.py

@@ -0,0 +1,236 @@
+"""Codebase archive storage for Run and Validator workspaces.
+
+Archives are content-addressed by the Run id, but hidden behind a small store
+interface. Local development writes files to disk; hosted deployments can
+persist compact archives in Redis so validation survives process restarts.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import json
+import os
+import shutil
+import tempfile
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from .redis_client import RedisClient, RedisStoreError, UpstashRedisRestClient
+
+
+LOCAL_ARCHIVE_SCHEME = "local-snapshot://"
+REDIS_ARCHIVE_SCHEME = "redis-archive://"
+DEFAULT_ARCHIVE_ROOT = Path(tempfile.gettempdir()) / "agent-swarm-workbench-codebases"
+ARCHIVE_FILE_MAX_BYTES = 10_000_000
+ARCHIVE_TOTAL_MAX_BYTES = 50_000_000
+ARCHIVE_IGNORED_DIR_NAMES = frozenset({"__pycache__"})
+ARCHIVE_IGNORED_SUFFIXES = (".pyc", ".pyo")
+
+
+class CodebaseArchiveError(ValueError):
+    pass
+
+
+class ArchiveFile(BaseModel):
+    path: str = Field(min_length=1)
+    content_base64: str
+    size_bytes: int = Field(ge=0, le=ARCHIVE_FILE_MAX_BYTES)
+
+    @field_validator("path")
+    @classmethod
+    def validate_path(cls, value: str) -> str:
+        return _safe_relative_path(value)
+
+
+class CodebaseArchiveSnapshot(BaseModel):
+    archive_id: str = Field(min_length=1)
+    files: list[ArchiveFile] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def validate_total_size(self) -> "CodebaseArchiveSnapshot":
+        total = sum(file.size_bytes for file in self.files)
+        if total > ARCHIVE_TOTAL_MAX_BYTES:
+            raise ValueError("codebase archive exceeds total size cap")
+        return self
+
+
+class CodebaseArchiveStore(Protocol):
+    def save(self, archive: CodebaseArchiveSnapshot) -> str:
+        ...
+
+    def load(self, archive_pointer: str) -> CodebaseArchiveSnapshot:
+        ...
+
+    def materialize(self, archive_pointer: str, destination: Path) -> None:
+        ...
+
+
+class LocalCodebaseArchiveStore:
+    def __init__(self, *, root_dir: Path | None = None) -> None:
+        self.root_dir = root_dir or DEFAULT_ARCHIVE_ROOT
+
+    def save(self, archive: CodebaseArchiveSnapshot) -> str:
+        destination = self.root_dir / archive.archive_id / "workspace"
+        if destination.exists():
+            shutil.rmtree(destination)
+        destination.mkdir(parents=True, exist_ok=True)
+        _write_archive_files(archive, destination)
+        return f"{LOCAL_ARCHIVE_SCHEME}{archive.archive_id}"
+
+    def load(self, archive_pointer: str) -> CodebaseArchiveSnapshot:
+        archive_id = _pointer_id(archive_pointer, LOCAL_ARCHIVE_SCHEME)
+        workspace = self.root_dir / archive_id / "workspace"
+        if not workspace.exists():
+            raise FileNotFoundError(f"snapshot workspace not found: {archive_id}")
+        return archive_from_directory(archive_id, workspace)
+
+    def materialize(self, archive_pointer: str, destination: Path) -> None:
+        archive = self.load(archive_pointer)
+        if destination.exists():
+            shutil.rmtree(destination)
+        destination.mkdir(parents=True, exist_ok=True)
+        _write_archive_files(archive, destination)
+
+
+@dataclass
+class RedisCodebaseArchiveStore:
+    client: RedisClient
+    key_prefix: str = "arena"
+    key_namespace: str = "codebase-archive"
+
+    def save(self, archive: CodebaseArchiveSnapshot) -> str:
+        key = self._key(archive.archive_id)
+        self.client.execute("SET", key, archive.model_dump_json())
+        return f"{REDIS_ARCHIVE_SCHEME}{archive.archive_id}"
+
+    def load(self, archive_pointer: str) -> CodebaseArchiveSnapshot:
+        archive_id = _pointer_id(archive_pointer, REDIS_ARCHIVE_SCHEME)
+        payload = self.client.execute("GET", self._key(archive_id))
+        if payload is None:
+            raise FileNotFoundError(f"codebase archive not found: {archive_id}")
+        try:
+            return CodebaseArchiveSnapshot.model_validate_json(str(payload))
+        except ValueError as exc:
+            raise RedisStoreError("codebase archive is invalid") from exc
+
+    def materialize(self, archive_pointer: str, destination: Path) -> None:
+        archive = self.load(archive_pointer)
+        if destination.exists():
+            shutil.rmtree(destination)
+        destination.mkdir(parents=True, exist_ok=True)
+        _write_archive_files(archive, destination)
+
+    def _key(self, archive_id: str) -> str:
+        return f"{self.key_prefix.rstrip(':')}:{self.key_namespace}:{archive_id}"
+
+
+def create_codebase_archive_store() -> CodebaseArchiveStore:
+    provider = (
+        os.getenv("CODEBASE_ARCHIVE_PROVIDER")
+        or os.getenv("MATCH_STORE_PROVIDER", "local")
+    )
+    provider = provider.lower()
+    if provider in {"local", "memory", "inmemory", "in-memory"}:
+        return LocalCodebaseArchiveStore()
+    if provider in {"redis", "upstash"}:
+        url = os.getenv("UPSTASH_REDIS_REST_URL", "")
+        token = os.getenv("UPSTASH_REDIS_REST_TOKEN", "")
+        if not url or not token:
+            raise ValueError(
+                "UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN are required "
+                "when CODEBASE_ARCHIVE_PROVIDER=redis"
+            )
+        return RedisCodebaseArchiveStore(client=UpstashRedisRestClient(url=url, token=token))
+    raise ValueError(f"Unsupported codebase archive provider: {provider}")
+
+
+def archive_from_directory(archive_id: str, workspace: Path) -> CodebaseArchiveSnapshot:
+    if not workspace.exists():
+        raise FileNotFoundError(f"workspace not found: {workspace}")
+    files = [
+        _archive_file(relative_path, path.read_bytes())
+        for path in sorted(workspace.rglob("*"))
+        for relative_path in [path.relative_to(workspace).as_posix()]
+        if path.is_file()
+        if not _is_ignored_archive_path(relative_path)
+    ]
+    return CodebaseArchiveSnapshot(archive_id=archive_id, files=files)
+
+
+def archive_from_downloads(
+    archive_id: str,
+    downloads: list[tuple[str, bytes]],
+) -> CodebaseArchiveSnapshot:
+    return CodebaseArchiveSnapshot(
+        archive_id=archive_id,
+        files=[
+            _archive_file(path, content)
+            for path, content in downloads
+            if not _is_ignored_archive_path(path)
+        ],
+    )
+
+
+def archive_to_zip_bytes(archive: CodebaseArchiveSnapshot) -> bytes:
+    buffer = io.BytesIO()
+    with zipfile.ZipFile(buffer, mode="w", compression=zipfile.ZIP_DEFLATED) as zipped:
+        for file in sorted(archive.files, key=lambda item: item.path):
+            zipped.writestr(
+                _safe_relative_path(file.path),
+                base64.b64decode(file.content_base64.encode("ascii")),
+            )
+    return buffer.getvalue()
+
+
+def supports_archive_pointer(archive_pointer: str) -> bool:
+    return archive_pointer.startswith(LOCAL_ARCHIVE_SCHEME) or archive_pointer.startswith(REDIS_ARCHIVE_SCHEME)
+
+
+def archive_to_json(archive: CodebaseArchiveSnapshot) -> str:
+    return json.dumps(archive.model_dump(mode="json"), sort_keys=True)
+
+
+def _archive_file(path: str, content: bytes) -> ArchiveFile:
+    safe_path = _safe_relative_path(path)
+    return ArchiveFile(
+        path=safe_path,
+        content_base64=base64.b64encode(content).decode("ascii"),
+        size_bytes=len(content),
+    )
+
+
+def _is_ignored_archive_path(path: str) -> bool:
+    relative = Path(path)
+    return (
+        any(part in ARCHIVE_IGNORED_DIR_NAMES for part in relative.parts)
+        or relative.suffix in ARCHIVE_IGNORED_SUFFIXES
+    )
+
+
+def _write_archive_files(archive: CodebaseArchiveSnapshot, destination: Path) -> None:
+    for file in archive.files:
+        relative = Path(_safe_relative_path(file.path))
+        target = destination / relative
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(base64.b64decode(file.content_base64.encode("ascii")))
+
+
+def _safe_relative_path(path: str) -> str:
+    relative = Path(path)
+    if relative.is_absolute() or not path or ".." in relative.parts:
+        raise CodebaseArchiveError(f"unsafe archive path: {path}")
+    return relative.as_posix()
+
+
+def _pointer_id(archive_pointer: str, scheme: str) -> str:
+    if not archive_pointer.startswith(scheme):
+        raise CodebaseArchiveError("unsupported archive pointer")
+    archive_id = archive_pointer.removeprefix(scheme)
+    if not archive_id or "/" in archive_id or ".." in archive_id:
+        raise CodebaseArchiveError("invalid archive pointer")
+    return archive_id

arena/codebase_executor.py

@@ -0,0 +1,183 @@
+"""Sandboxed command executors for Codebase archives."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any, Callable
+from uuid import uuid4
+
+from deepagents.backends import LocalShellBackend
+
+from .codebase_archive import (
+    CodebaseArchiveStore,
+    LocalCodebaseArchiveStore,
+    create_codebase_archive_store,
+)
+from .codebase_handoff import (
+    CodebaseHandoff,
+    DEFAULT_CODEBASE_HANDOFF_ROOT,
+    local_snapshot_workspace,
+    pointer_error,
+)
+from .sandbox_lease import SandboxLeaseManager
+
+
+DEFAULT_SNAPSHOT_ROOT = DEFAULT_CODEBASE_HANDOFF_ROOT
+DEFAULT_VALIDATOR_SANDBOX_ROOT = Path(tempfile.gettempdir()) / "agent-swarm-workbench-validator"
+
+
+class LocalCodebaseExecutor:
+    """Runs validation checks against local Codebase archive materializations."""
+
+    def __init__(self, *, root_dir: Path | None = None, timeout_seconds: int = 20) -> None:
+        self.root_dir = root_dir or DEFAULT_SNAPSHOT_ROOT
+        self.timeout_seconds = timeout_seconds
+
+    def run(self, archive_pointer: str, command: str) -> tuple[bool, str]:
+        workspace = local_snapshot_workspace(self.root_dir, archive_pointer)
+        if workspace is None:
+            return False, pointer_error(archive_pointer)
+        if not workspace.exists():
+            return False, f"snapshot workspace not found: {archive_pointer}"
+
+        try:
+            result = subprocess.run(
+                ["/bin/sh", "-lc", command],
+                cwd=workspace,
+                capture_output=True,
+                text=True,
+                timeout=self.timeout_seconds,
+                env={"PATH": _executor_path()},
+                check=False,
+            )
+        except subprocess.TimeoutExpired as exc:
+            output = (exc.stdout or "") + (exc.stderr or "")
+            return False, f"{output}\n[Command timed out after {self.timeout_seconds}s]"
+
+        output = result.stdout
+        if result.stderr:
+            output = f"{output}[stderr] {result.stderr}"
+        status = "succeeded" if result.returncode == 0 else "failed"
+        return result.returncode == 0, f"{output}\n[Command {status} with exit code {result.returncode}]"
+
+
+class CodebaseSandboxExecutor:
+    """Restores Codebase archives into a sandbox backend before running checks."""
+
+    def __init__(
+        self,
+        *,
+        backend_factory: Callable[[], Any],
+        root_dir: Path | None = None,
+        archive_store: CodebaseArchiveStore | None = None,
+        timeout_seconds: int = 20,
+        sandbox_ttl_seconds: float | None = None,
+        sandbox_leases: SandboxLeaseManager | None = None,
+    ) -> None:
+        self.root_dir = root_dir or DEFAULT_SNAPSHOT_ROOT
+        self.archive_store = archive_store or LocalCodebaseArchiveStore(root_dir=self.root_dir)
+        self.handoff = CodebaseHandoff(archive_store=self.archive_store, root_dir=self.root_dir)
+        self.backend_factory = backend_factory
+        self.backend = None
+        self.timeout_seconds = timeout_seconds
+        self.workspace_dir = "workspace"
+        self._restored: set[str] = set()
+        self._lease_id = f"validator-{uuid4().hex}"
+        self._sandbox_leases = sandbox_leases or SandboxLeaseManager(ttl_seconds=sandbox_ttl_seconds)
+
+    def run(self, archive_pointer: str, command: str) -> tuple[bool, str]:
+        self._ensure_backend()
+        self._sandbox_leases.touch(self._lease_id)
+        try:
+            self._restore(archive_pointer)
+        except (OSError, ValueError) as exc:
+            return False, f"could not restore snapshot: {exc}"
+
+        result = self.backend.execute(f"cd {shlex.quote(self.workspace_dir)} && {command}", timeout=self.timeout_seconds)
+        output = getattr(result, "output", "")
+        exit_code = getattr(result, "exit_code", None)
+        if exit_code is None:
+            return True, output
+        status = "succeeded" if exit_code == 0 else "failed"
+        return exit_code == 0, f"{output}\n[Command {status} with exit code {exit_code}]"
+
+    def close(self) -> None:
+        self._sandbox_leases.close(self._lease_id)
+
+    def _open_backend(self) -> None:
+        self.backend = self.backend_factory()
+        self.workspace_dir = getattr(self.backend, "_validator_workspace", "workspace")
+        self._restored = set()
+        self._sandbox_leases.start(self._lease_id, self._close_backend)
+
+    def _ensure_backend(self) -> None:
+        if self.backend is None:
+            self._open_backend()
+
+    def _close_backend(self) -> None:
+        if self.backend is None:
+            return
+        sandbox = getattr(self.backend, "_daytona_sandbox", None)
+        cleanup = None
+        if sandbox is not None:
+            cleanup = getattr(sandbox, "delete", None) or getattr(sandbox, "stop", None)
+        if cleanup is None:
+            cleanup = getattr(self.backend, "delete", None) or getattr(self.backend, "stop", None)
+        if callable(cleanup):
+            cleanup()
+        self.backend = None
+        self._restored = set()
+
+    def _restore(self, archive_pointer: str) -> None:
+        if archive_pointer in self._restored:
+            return
+        self.handoff.restore_to_backend(
+            archive_pointer,
+            self.backend,
+            workspace_dir=self.workspace_dir,
+        )
+        self._restored.add(archive_pointer)
+
+
+def create_codebase_executor(
+    archive_store: CodebaseArchiveStore | None = None,
+    provider: str | None = None,
+) -> CodebaseSandboxExecutor:
+    provider = (provider or os.getenv("VALIDATOR_SANDBOX_PROVIDER", "local")).lower()
+    archive_store = archive_store or create_codebase_archive_store()
+    if provider == "local":
+        return CodebaseSandboxExecutor(backend_factory=_local_validator_backend, archive_store=archive_store)
+    if provider == "daytona":
+        return CodebaseSandboxExecutor(backend_factory=_daytona_validator_backend, archive_store=archive_store)
+    raise ValueError(f"unsupported validator sandbox provider: {provider}")
+
+
+def _executor_path() -> str:
+    executable_dir = str(Path(sys.executable).parent)
+    return os.pathsep.join([executable_dir, "/usr/local/bin", "/usr/bin", "/bin"])
+
+
+def _local_validator_backend() -> LocalShellBackend:
+    root = DEFAULT_VALIDATOR_SANDBOX_ROOT / uuid4().hex
+    root.mkdir(parents=True, exist_ok=True)
+    backend = LocalShellBackend(root_dir=root, virtual_mode=True, inherit_env=True)
+    backend._validator_workspace = "workspace"
+    return backend
+
+
+def _daytona_validator_backend() -> Any:
+    from daytona import Daytona
+    from langchain_daytona import DaytonaSandbox
+
+    client = Daytona()
+    sandbox = client.create()
+    backend = DaytonaSandbox(sandbox=sandbox)
+    backend._daytona_client = client
+    backend._daytona_sandbox = sandbox
+    backend._validator_workspace = "/home/daytona/workspace"
+    return backend

arena/codebase_handoff.py

@@ -0,0 +1,156 @@
+"""Codebase handoff between Swarm workspaces, archives, and Validator sandboxes."""
+
+from __future__ import annotations
+
+import re
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .codebase_archive import (
+    CodebaseArchiveStore,
+    LocalCodebaseArchiveStore,
+    archive_from_directory,
+    archive_from_downloads,
+    supports_archive_pointer,
+)
+
+
+DEFAULT_CODEBASE_HANDOFF_ROOT = Path(tempfile.gettempdir()) / "agent-swarm-workbench-codebases"
+LOCAL_SNAPSHOT_SCHEME = "local-snapshot://"
+CODEBASE_ID_PATTERN = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+@dataclass
+class CodebaseHandoff:
+    """Moves a Codebase across Workspace, archive, and Validator sandbox seams."""
+
+    archive_store: CodebaseArchiveStore | None = None
+    root_dir: Path | None = None
+
+    def __post_init__(self) -> None:
+        root = self.root_dir or DEFAULT_CODEBASE_HANDOFF_ROOT
+        if self.archive_store is None:
+            self.archive_store = LocalCodebaseArchiveStore(root_dir=root)
+
+    def snapshot_local_workspace(self, source_root: Path, codebase_id: str) -> str:
+        _validate_codebase_id(codebase_id)
+        return self.archive_store.save(archive_from_directory(codebase_id, source_root / "workspace"))
+
+    def snapshot_backend_workspace(
+        self,
+        backend: Any,
+        codebase_id: str,
+        *,
+        workspace_dir: str = "/workspace",
+    ) -> str:
+        _validate_codebase_id(codebase_id)
+        workspace_dir = normalize_workspace_dir(workspace_dir)
+        glob_result = backend.glob(f"{workspace_dir}/**")
+        if getattr(glob_result, "error", None):
+            raise RuntimeError("could not list workspace files")
+
+        file_paths = [
+            _entry_path(match)
+            for match in getattr(glob_result, "matches", [])
+            if not _entry_is_dir(match)
+        ]
+        if not file_paths:
+            raise FileNotFoundError("workspace has no files")
+
+        archive_files: list[tuple[str, bytes]] = []
+        for item in backend.download_files(file_paths):
+            if getattr(item, "error", None):
+                raise RuntimeError(f"could not download workspace file: {getattr(item, 'path', '')}")
+            source_path = str(getattr(item, "path", ""))
+            relative = workspace_relative_path(source_path, workspace_dir=workspace_dir)
+            archive_files.append((relative.as_posix(), getattr(item, "content", b"") or b""))
+
+        return self.archive_store.save(archive_from_downloads(codebase_id, archive_files))
+
+    def restore_to_backend(
+        self,
+        archive_pointer: str,
+        backend: Any,
+        *,
+        workspace_dir: str,
+    ) -> int:
+        if not supports_archive_pointer(archive_pointer):
+            raise ValueError(pointer_error(archive_pointer))
+
+        workspace = (self.root_dir or DEFAULT_CODEBASE_HANDOFF_ROOT) / restore_id(archive_pointer) / "workspace"
+        self.archive_store.materialize(archive_pointer, workspace)
+        files = [
+            (sandbox_workspace_path(workspace_dir, path.relative_to(workspace).as_posix()), path.read_bytes())
+            for path in workspace.rglob("*")
+            if path.is_file()
+        ]
+        results = backend.upload_files(files)
+        for result in results:
+            if getattr(result, "error", None):
+                raise RuntimeError(
+                    f"could not upload file: {getattr(result, 'path', '')}: {getattr(result, 'error', '')}"
+                )
+        return len(files)
+
+
+def local_snapshot_workspace(root_dir: Path, archive_pointer: str) -> Path | None:
+    snapshot_id = local_snapshot_id(archive_pointer)
+    if snapshot_id is None:
+        return None
+    return root_dir / snapshot_id / "workspace"
+
+
+def local_snapshot_id(archive_pointer: str) -> str | None:
+    if not archive_pointer.startswith(LOCAL_SNAPSHOT_SCHEME):
+        return None
+    snapshot_id = archive_pointer.removeprefix(LOCAL_SNAPSHOT_SCHEME)
+    if not CODEBASE_ID_PATTERN.fullmatch(snapshot_id):
+        return None
+    return snapshot_id
+
+
+def restore_id(archive_pointer: str) -> str:
+    if "://" not in archive_pointer:
+        raise ValueError("unsupported archive pointer")
+    snapshot_id = archive_pointer.split("://", 1)[1]
+    _validate_codebase_id(snapshot_id)
+    return snapshot_id
+
+
+def pointer_error(archive_pointer: str) -> str:
+    if archive_pointer.startswith(LOCAL_SNAPSHOT_SCHEME):
+        return "invalid snapshot id"
+    return "unsupported archive pointer"
+
+
+def normalize_workspace_dir(workspace_dir: str) -> str:
+    return workspace_dir.rstrip("/") or "/workspace"
+
+
+def workspace_relative_path(path: str, *, workspace_dir: str = "/workspace") -> Path:
+    prefix = f"{normalize_workspace_dir(workspace_dir)}/"
+    if not path.startswith(prefix):
+        raise ValueError(f"path outside workspace: {path}")
+    relative = path.removeprefix(prefix)
+    if not relative or ".." in Path(relative).parts:
+        raise ValueError(f"unsafe workspace path: {path}")
+    return Path(relative)
+
+
+def sandbox_workspace_path(workspace_dir: str, relative_path: str) -> str:
+    return f"{normalize_workspace_dir(workspace_dir)}/{relative_path}"
+
+
+def _validate_codebase_id(codebase_id: str) -> None:
+    if not CODEBASE_ID_PATTERN.fullmatch(codebase_id):
+        raise ValueError("invalid codebase id")
+
+
+def _entry_path(entry: Any) -> str:
+    return str(entry.get("path", "") if isinstance(entry, dict) else getattr(entry, "path", ""))
+
+
+def _entry_is_dir(entry: Any) -> bool:
+    return bool(entry.get("is_dir") if isinstance(entry, dict) else getattr(entry, "is_dir", False))

arena/docker_backend.py

@@ -0,0 +1,179 @@
+"""Docker-based sandbox backend for isolated execution.
+
+Uses ``subprocess`` to manage a single container, avoiding extra dependencies.
+"""
+
+from __future__ import annotations
+
+import json
+import shlex
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any
+
+
+class DockerSandboxBackend:
+    """A sandbox backend backed by a Docker container for process isolation."""
+
+    def __init__(
+        self,
+        image: str = "python:3.11-slim",
+        timeout_seconds: int = 20,
+    ) -> None:
+        self._image = image
+        self._timeout = timeout_seconds
+        self._container_id: str | None = None
+        self._workspace_dir = "/workspace"
+        self._start_container()
+
+    def _start_container(self) -> None:
+        result = subprocess.run(
+            [
+                "docker", "run", "-d", "--rm",
+                "-w", "/workspace",
+                self._image,
+                "tail", "-f", "/dev/null",
+            ],
+            capture_output=True, text=True, timeout=30,
+            check=False,
+        )
+        if result.returncode != 0:
+            stderr = result.stderr.strip()
+            if "docker" in stderr.lower() and ("not found" in stderr.lower() or "daemon" in stderr.lower()):
+                raise RuntimeError(
+                    "Docker is not available. Install Docker or set DEEPAGENT_SANDBOX_PROVIDER=local."
+                )
+            raise RuntimeError(f"Failed to start Docker container: {stderr}")
+        self._container_id = result.stdout.strip()
+        self._exec("mkdir", "-p", self._workspace_dir)
+
+    def write(self, path: str, content: str) -> Any:
+        return self._copy_to(path, content.encode("utf-8"))
+
+    def read(self, path: str) -> Any:
+        data = self._copy_from(path)
+        content = data.decode("utf-8") if isinstance(data, bytes) else str(data)
+        return type("ReadResult", (), {"error": None, "file_data": {"content": content}})()
+
+    def ls(self, path: str) -> Any:
+        output = self._exec_output("find", path.rstrip("/"), "-maxdepth", "1", "-printf", "%p\t%y\n")
+        entries = []
+        for line in output.splitlines():
+            if not line.strip():
+                continue
+            parts = line.split("\t")
+            if len(parts) < 2:
+                continue
+            filepath, kind = parts[0], parts[1]
+            if filepath == path.rstrip("/"):
+                continue
+            entries.append({"path": filepath, "is_dir": kind == "d"})
+        return type("LsResult", (), {"error": None, "entries": entries})()
+
+    def execute(self, command: str, timeout: int | None = None) -> Any:
+        t = timeout or self._timeout
+        result = subprocess.run(
+            ["docker", "exec", self._container_id, "sh", "-c", command],
+            capture_output=True, text=True, timeout=t,
+            check=False,
+        )
+        output = result.stdout
+        if result.stderr:
+            output = f"{output}\n{result.stderr}"
+        return type("ExecResult", (), {"error": None, "output": output, "exit_code": result.returncode})()
+
+    def glob(self, pattern: str) -> Any:
+        find_pattern = "/".join(
+            part.replace("**", ".").replace("*", "[^/]*") if part != "**" else part
+            for part in pattern.split("/")
+        )
+        output = self._exec_output("find", "/", "-path", pattern, "-not", "-type", "d")
+        matches = []
+        for line in output.splitlines():
+            line = line.strip()
+            if line:
+                matches.append({"path": line, "is_dir": False})
+        return type("GlobResult", (), {"error": None, "matches": matches})()
+
+    def download_files(self, paths: list[str]) -> list[Any]:
+        results = []
+        for path in paths:
+            try:
+                data = self._copy_from(path)
+                results.append(type("DownloadResult", (), {"error": None, "path": path, "content": data})())
+            except Exception as exc:
+                results.append(type("DownloadResult", (), {"error": str(exc), "path": path, "content": b""})())
+        return results
+
+    def upload_files(self, files: list[tuple[str, bytes]]) -> list[Any]:
+        results = []
+        for path, content in files:
+            try:
+                self._copy_to(path, content)
+                results.append(type("UploadResult", (), {"error": None, "path": path})())
+            except Exception as exc:
+                results.append(type("UploadResult", (), {"error": str(exc), "path": path})())
+        return results
+
+    def stop(self) -> None:
+        if self._container_id:
+            subprocess.run(
+                ["docker", "rm", "-f", self._container_id],
+                capture_output=True, timeout=10, check=False,
+            )
+            self._container_id = None
+
+    def delete(self) -> None:
+        self.stop()
+
+    def _exec_output(self, *cmd: str) -> str:
+        result = subprocess.run(
+            ["docker", "exec", self._container_id, *cmd],
+            capture_output=True, text=True, timeout=self._timeout,
+            check=False,
+        )
+        return result.stdout
+
+    def _exec(self, *cmd: str) -> None:
+        result = subprocess.run(
+            ["docker", "exec", self._container_id, *cmd],
+            capture_output=True, text=True, timeout=self._timeout,
+            check=False,
+        )
+        if result.returncode != 0:
+            raise RuntimeError(f"Docker exec failed: {result.stderr.strip()}")
+
+    def _copy_to(self, container_path: str, content: bytes) -> Any:
+        with tempfile.NamedTemporaryFile(delete=False) as tmp:
+            tmp.write(content)
+            tmp_path = tmp.name
+        try:
+            result = subprocess.run(
+                ["docker", "cp", tmp_path, f"{self._container_id}:{shlex.quote(container_path)}"],
+                capture_output=True, text=True, timeout=self._timeout,
+                check=False,
+            )
+        finally:
+            Path(tmp_path).unlink(missing_ok=True)
+        if result.returncode != 0:
+            raise RuntimeError(f"docker cp failed: {result.stderr.strip()}")
+        return type("WriteResult", (), {"error": None})()
+
+    def _copy_from(self, container_path: str) -> bytes:
+        with tempfile.NamedTemporaryFile(delete=False) as tmp:
+            tmp_path = tmp.name
+        try:
+            result = subprocess.run(
+                ["docker", "cp", f"{self._container_id}:{shlex.quote(container_path)}", tmp_path],
+                capture_output=True, text=True, timeout=self._timeout,
+                check=False,
+            )
+            if result.returncode != 0:
+                raise RuntimeError(f"docker cp failed: {result.stderr.strip()}")
+            return Path(tmp_path).read_bytes()
+        finally:
+            Path(tmp_path).unlink(missing_ok=True)
+
+    def _workspace_dir(self) -> str:
+        return self._workspace_dir

arena/event_bus.py

@@ -0,0 +1,36 @@
+"""In-process event bus for Run event streaming."""
+
+from __future__ import annotations
+
+import queue
+from typing import Any, Callable
+
+
+EventListener = Callable[[str, dict[str, Any]], None]
+
+
+class EventBus:
+    def __init__(self) -> None:
+        self._queues: dict[str, queue.Queue[dict[str, Any] | None]] = {}
+        self._listeners: dict[str, list[EventListener]] = {}
+
+    def subscribe(self, run_id: str) -> queue.Queue[dict[str, Any] | None]:
+        q: queue.Queue[dict[str, Any] | None] = queue.Queue()
+        self._queues[run_id] = q
+        return q
+
+    def publish(self, run_id: str, event: dict[str, Any]) -> None:
+        for listener in self._listeners.get(run_id, []):
+            listener(run_id, event)
+        q = self._queues.get(run_id)
+        if q is not None:
+            q.put(event)
+
+    def close(self, run_id: str) -> None:
+        self._listeners.pop(run_id, None)
+        q = self._queues.pop(run_id, None)
+        if q is not None:
+            q.put(None)
+
+    def add_listener(self, run_id: str, listener: EventListener) -> None:
+        self._listeners.setdefault(run_id, []).append(listener)

arena/gradio_app.py

@@ -0,0 +1,1141 @@
+"""Prompt-first Gradio surface for Backyard Demo Builder."""
+
+from __future__ import annotations
+
+import gradio as gr
+
+from .gradio_markup import FOOTER_HTML, HERO_HTML, RAIL_HTML, TOPBAR_HTML
+from .gradio_presenter import RunOutputs, UiState, empty_outputs, run_outputs
+from .backyard_templates import template_by_label, template_choices
+from .gradio_run import (
+    DEFAULT_BACKYARD_CHECKS,
+    DEFAULT_BACKYARD_CRITERIA,
+    DEFAULT_BACKYARD_PROMPT,
+    run_request_from_text,
+)
+from .model_catalog import ModelProviderConfig, eligible_models
+from .service import ArenaService
+
+HOSTED_MODEL_PROVIDERS = {"openrouter", "gemini", "nebius", "huggingface", "hf"}
+
+
+try:
+    import spaces
+except Exception:
+    class _SpacesShim:
+        def GPU(self, fn=None, **kwargs):
+            del kwargs
+
+            def decorator(inner):
+                return inner
+
+            return decorator(fn) if fn else decorator
+
+    spaces = _SpacesShim()
+
+
+class GradioArena:
+    def __init__(self, service: ArenaService | None = None) -> None:
+        self.service = service or ArenaService()
+
+    def create_run(
+        self,
+        prompt: str,
+        criteria_text: str,
+        user_tests_text: str,
+        provider: str = "openrouter",
+        model: str = "",
+        api_key: str = "",
+        base_url: str = "",
+    ) -> RunOutputs:
+        provider = provider or "openrouter"
+        model = model or ""
+        api_key = api_key or ""
+        base_url = base_url or ""
+        if _requires_user_key(provider) and not api_key.strip():
+            return self._empty(
+                UiState(),
+                "Choose a fetched model and enter your own API key. Server API keys are not used by default.",
+            )
+        request = run_request_from_text(prompt, criteria_text, user_tests_text, provider, model, api_key, base_url)
+        if _is_local_zerogpu_provider(provider, base_url):
+            access = self.service.create_run(request)
+        else:
+            access = self.service.start_run(request)
+        state = UiState(role="run", run_id=access.run.id)
+        return self._run_outputs(state)
+
+    def rejoin_run(self, token: str) -> RunOutputs:
+        access = self.service.rejoin_run(token.strip())
+        state = UiState(role="run", run_id=access.run.id)
+        return self._run_outputs(state)
+
+    def cancel_run(self, state: UiState) -> RunOutputs:
+        if state.role != "run" or not state.run_id:
+            return self._empty(state, "No active run")
+        self.service.cancel_run(state.run_id)
+        return self._run_outputs(state)
+
+    def send_message(self, state: UiState, message: str) -> RunOutputs:
+        if state.role != "run" or not state.run_id:
+            return self._empty(state, "No active run")
+        if message.strip():
+            self.service.add_run_message(state.run_id, message.strip())
+        return self._run_outputs(state)
+
+    def record_feedback(
+        self,
+        state: UiState,
+        tester: str,
+        quote: str,
+        decision: str,
+        notes: str,
+    ) -> RunOutputs:
+        if state.role != "run" or not state.run_id:
+            return self._empty(state, "No active run")
+        parts = [
+            "Mom Test feedback",
+            f"Tester: {tester.strip() or 'Mom'}",
+            f"Decision: {decision.strip() or 'undecided'}",
+        ]
+        if quote.strip():
+            parts.append(f"Quote: {quote.strip()}")
+        if notes.strip():
+            parts.append(f"Notes: {notes.strip()}")
+        self.service.add_run_message(state.run_id, "\n".join(parts))
+        return self._run_outputs(state)
+
+    def refresh(self, state: UiState) -> RunOutputs:
+        if state.role != "run" or not state.run_id:
+            return self._empty(state, "No active run")
+        return self._run_outputs(state)
+
+    def refresh_models(self, provider: str | None, api_key: str | None, base_url: str | None):
+        api_key = api_key or ""
+        base_url = base_url or ""
+        models = self.service.refresh_provider_models(
+            ModelProviderConfig(
+                provider=provider or "openrouter",
+                api_key=api_key.strip() or None,
+                base_url=base_url.strip(),
+            )
+        )
+        selectable_models = list(eligible_models(models))
+        choices = [model.id for model in selectable_models]
+        value = choices[0] if choices else None
+        return gr.Dropdown(choices=choices, value=value), [model.model_dump() for model in selectable_models]
+
+    def apply_template(self, label: str) -> tuple[str, str, str]:
+        template = template_by_label(label)
+        return template.prompt, template.criteria, template.checks
+
+    def _run_outputs(self, state: UiState) -> RunOutputs:
+        run = self.service.get_run(state.run_id)
+        return run_outputs(state, run)
+
+    def _empty(self, state: UiState, message: str) -> RunOutputs:
+        return empty_outputs(state, message)
+
+
+def _requires_user_key(provider: str) -> bool:
+    return provider.strip().lower().replace("_", "-") in HOSTED_MODEL_PROVIDERS
+
+
+@spaces.GPU(duration=1)
+def zerogpu_ready_marker() -> str:
+    return "ready"
+
+
+def _is_local_zerogpu_provider(provider: str, base_url: str) -> bool:
+    return provider.strip().lower().replace("_", "-") == "local" and not base_url.strip()
+
+
+THEME = gr.themes.Base(
+    primary_hue="neutral",
+    secondary_hue="neutral",
+    neutral_hue="neutral",
+    font=["Geist", "Inter", "system-ui", "sans-serif"],
+    font_mono=["IBM Plex Mono", "SFMono-Regular", "ui-monospace", "monospace"],
+).set(
+    body_background_fill="#0a0a0a",
+    body_background_fill_dark="#0a0a0a",
+    block_background_fill="#111113",
+    block_background_fill_dark="#111113",
+    block_border_width="1px",
+    block_border_color="#27272a",
+    block_border_color_dark="#27272a",
+    block_title_text_color="#fafafa",
+    block_title_text_color_dark="#fafafa",
+    block_label_text_color="#a1a1aa",
+    block_label_text_color_dark="#a1a1aa",
+    input_background_fill="#0a0a0a",
+    input_background_fill_dark="#0a0a0a",
+    input_border_color="#27272a",
+    input_border_color_dark="#27272a",
+    input_radius="0px",
+    button_primary_background_fill="#fafafa",
+    button_primary_background_fill_hover="#e4e4e7",
+    button_primary_border_color="#fafafa",
+    button_primary_text_color="#0a0a0a",
+    button_secondary_background_fill="#0a0a0a",
+    button_secondary_background_fill_hover="#1f1f23",
+    button_secondary_border_color="#3f3f46",
+    button_secondary_text_color="#fafafa",
+    button_cancel_background_fill="#0a0a0a",
+    button_cancel_background_fill_hover="#1f1f23",
+    button_cancel_border_color="#3f3f46",
+    button_cancel_text_color="#fafafa",
+    button_large_radius="0px",
+    checkbox_label_text_color="#fafafa",
+    checkbox_background_color="#0a0a0a",
+    checkbox_border_color="#3f3f46",
+)
+
+
+CSS = """
+:root {
+  --bg: #0a0a0a;
+  --panel: #111113;
+  --panel-soft: #18181b;
+  --panel-strong: #050505;
+  --ink: #fafafa;
+  --ink-soft: #e4e4e7;
+  --muted: #a1a1aa;
+  --faint: #71717a;
+  --rule: #27272a;
+  --rule-strong: #3f3f46;
+  --sans: "Geist", "Inter", system-ui, -apple-system, sans-serif;
+  --mono: "IBM Plex Mono", "SFMono-Regular", ui-monospace, monospace;
+
+  --container-pad: clamp(24px, 3vw, 56px);
+  --container-pad-sm: 20px;
+  --section-gap: clamp(32px, 5vw, 96px);
+  --hero-py-top: clamp(80px, 10vw, 120px);
+  --hero-py-bottom: clamp(56px, 6vw, 80px);
+  --hero-cols: minmax(0, 1.4fr) minmax(280px, 380px);
+  --hero-grid-size: 96px 100%;
+  --hero-grid-line: rgba(255, 255, 255, 0.022);
+  --hero-title-size: clamp(44px, 5.4vw, 96px);
+  --workbench-cols: minmax(0, 1.6fr) minmax(320px, 380px) minmax(0, 1fr);
+  --workbench-cols-md: minmax(0, 1.5fr) minmax(320px, 360px);
+}
+
+footer:not(.footer) { display: none !important; }
+
+html, body {
+  background: var(--bg) !important;
+  color: var(--ink) !important;
+  font-family: var(--sans) !important;
+  font-feature-settings: "ss01", "cv11";
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+* { letter-spacing: 0 !important; }
+
+.gradio-container {
+  max-width: 100% !important;
+  background: var(--bg) !important;
+  padding: 0 var(--container-pad) !important;
+}
+
+#run-shell {
+  padding: 0 !important;
+  background: var(--bg) !important;
+  max-width: 100% !important;
+}
+
+.block,
+.form,
+.panel,
+.gr-box {
+  border-radius: 0 !important;
+  box-shadow: none !important;
+  background: var(--panel) !important;
+  border-color: var(--rule) !important;
+}
+
+.contain { border-radius: 0 !important; }
+
+label,
+.gr-textbox label,
+.gr-dataframe label,
+.gr-button {
+  font-family: var(--mono) !important;
+  color: var(--muted) !important;
+  text-transform: uppercase !important;
+  font-size: 10.5px !important;
+  font-weight: 600 !important;
+  letter-spacing: 0.14em !important;
+}
+
+label { color: var(--muted) !important; }
+
+textarea,
+input {
+  color: var(--ink) !important;
+  background: var(--panel) !important;
+  font-family: var(--mono) !important;
+  font-size: 13px !important;
+  line-height: 1.55 !important;
+  border: 1px solid var(--rule) !important;
+}
+
+textarea::placeholder,
+input::placeholder {
+  color: var(--faint) !important;
+  opacity: 1 !important;
+  font-family: var(--mono) !important;
+}
+
+textarea:focus,
+input:focus {
+  outline: none !important;
+  border-color: var(--ink) !important;
+  box-shadow: 0 0 0 1px var(--ink) !important;
+}
+
+button {
+  background: var(--panel) !important;
+  color: var(--ink) !important;
+  border-radius: 0 !important;
+  border: 1px solid var(--rule-strong) !important;
+  box-shadow: none !important;
+  font-family: var(--mono) !important;
+  font-weight: 600 !important;
+  letter-spacing: 0.14em !important;
+  text-transform: uppercase !important;
+  font-size: 11px !important;
+  transition:
+    background 120ms ease,
+    color 120ms ease,
+    border-color 120ms ease,
+    transform 120ms ease !important;
+}
+
+button:hover {
+  background: var(--ink) !important;
+  color: var(--bg) !important;
+  border-color: var(--ink) !important;
+}
+
+button:active { transform: translateY(1px); }
+
+#start-run-btn {
+  min-height: 52px !important;
+  background: var(--ink) !important;
+  color: var(--bg) !important;
+  border-color: var(--ink) !important;
+  font-size: 12px !important;
+}
+
+#start-run-btn:hover {
+  background: var(--ink-soft) !important;
+  border-color: var(--ink-soft) !important;
+}
+
+#cancel-run-btn,
+#refresh-run-btn,
+#send-message-btn {
+  min-height: 40px !important;
+}
+
+.dataframe,
+table {
+  font-family: var(--mono) !important;
+  font-size: 11.5px !important;
+  background: var(--panel) !important;
+  color: var(--ink) !important;
+  border-color: var(--rule) !important;
+}
+
+.dataframe thead,
+table thead {
+  background: var(--panel-soft) !important;
+  color: var(--muted) !important;
+  text-transform: uppercase !important;
+  letter-spacing: 0.12em !important;
+  font-size: 10.5px !important;
+  font-weight: 600 !important;
+}
+
+.dataframe td,
+.dataframe th,
+table td,
+table th {
+  border-color: var(--rule) !important;
+  padding: 8px 12px !important;
+}
+
+.topbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  height: 64px;
+  padding: 0 var(--container-pad);
+  border-bottom: 1px solid var(--rule);
+  background: var(--bg);
+}
+
+.topbar .wordmark {
+  margin: 0;
+  font-family: var(--mono);
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.18em;
+  color: var(--ink);
+}
+
+.topbar .wordmark-dot {
+  display: inline-block;
+  width: 6px;
+  height: 6px;
+  background: var(--ink);
+  margin-right: 10px;
+  vertical-align: middle;
+}
+
+.topbar .topbar-meta {
+  margin: 0;
+  font-family: var(--mono);
+  font-size: 10.5px;
+  text-transform: uppercase;
+  letter-spacing: 0.18em;
+  color: var(--faint);
+}
+
+#status-bar {
+  position: fixed !important;
+  top: 16px;
+  right: var(--container-pad);
+  z-index: 100;
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 8px;
+  background: transparent !important;
+  border: 0 !important;
+  padding: 6px 10px !important;
+  width: max-content !important;
+  max-width: 280px !important;
+  box-shadow: none !important;
+  margin: 0 !important;
+}
+
+#status-bar:not(:has(.run-status-chip)) { display: none !important; }
+
+.hero {
+  display: grid;
+  grid-template-columns: var(--hero-cols);
+  gap: var(--section-gap);
+  align-items: end;
+  padding: var(--hero-py-top) var(--container-pad) var(--hero-py-bottom);
+  border-bottom: 1px solid var(--rule);
+  background-image:
+    linear-gradient(to right, var(--hero-grid-line) 1px, transparent 1px);
+  background-size: var(--hero-grid-size);
+  background-position: 0 0;
+}
+
+.hero-main {
+  display: flex;
+  flex-direction: column;
+  gap: clamp(20px, 2vw, 32px);
+}
+
+.hero-side {
+  padding-bottom: 12px;
+}
+
+.hero-marks {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+  border-top: 1px solid var(--rule);
+}
+
+.hero-marks li {
+  display: grid;
+  grid-template-columns: 56px 1fr;
+  gap: 16px;
+  align-items: baseline;
+  padding: 18px 0;
+  border-bottom: 1px solid var(--rule);
+}
+
+.mark-num {
+  font-family: var(--mono);
+  font-size: 10.5px;
+  letter-spacing: 0.18em;
+  color: var(--faint);
+  text-transform: uppercase;
+}
+
+.mark-text {
+  font-family: var(--mono);
+  font-size: 12.5px;
+  line-height: 1.5;
+  color: var(--ink);
+}
+
+.hero .hero-title {
+  margin: 0;
+  max-width: 980px;
+  font-family: var(--sans);
+  font-size: var(--hero-title-size) !important;
+  line-height: 0.96 !important;
+  font-weight: 700 !important;
+  letter-spacing: -0.025em;
+  color: var(--ink);
+}
+
+.hero .hero-title .line {
+  display: block;
+}
+
+.hero .hero-title .line-accent {
+  color: var(--muted);
+  font-style: normal;
+}
+
+.hero .hero-subtext {
+  max-width: 620px;
+  margin: 0;
+  font-family: var(--mono);
+  font-size: 13.5px;
+  line-height: 1.7;
+  color: var(--muted);
+}
+
+.workbench {
+  display: grid;
+  grid-template-columns: var(--workbench-cols);
+  gap: 0;
+  border-bottom: 1px solid var(--rule);
+}
+
+.workbench .workbench-input {
+  padding: 40px var(--container-pad) 40px var(--container-pad);
+  border-right: 1px solid var(--rule);
+}
+
+.workbench .workbench-dispatch {
+  padding: 40px clamp(20px, 2vw, 36px);
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+  background: var(--panel-soft);
+  border-right: 1px solid var(--rule);
+}
+
+.workbench .workbench-rail {
+  padding: 40px var(--container-pad) 40px clamp(20px, 2vw, 36px);
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  background: var(--bg);
+}
+
+.rail-block {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  padding: 16px 18px;
+  border: 1px solid var(--rule);
+  background: var(--panel);
+}
+
+.rail-grid {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.rail-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  font-family: var(--mono);
+  font-size: 11px;
+  color: var(--muted);
+}
+
+.rail-label {
+  text-transform: uppercase;
+  letter-spacing: 0.14em;
+  font-size: 10px;
+  color: var(--faint);
+}
+
+.rail-value {
+  color: var(--ink);
+  text-align: right;
+}
+
+.rail-kbd {
+  color: var(--ink);
+  font-family: var(--mono);
+  font-size: 10.5px;
+  text-align: right;
+  letter-spacing: 0.04em;
+}
+
+.rail-status-block {
+  gap: 8px;
+}
+
+.rail-status-text {
+  margin: 0;
+  font-family: var(--mono);
+  font-size: 11.5px;
+  line-height: 1.6;
+  color: var(--muted);
+}
+
+.field-stack {
+  display: flex;
+  flex-direction: column;
+  gap: 24px;
+}
+
+.field-pair {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 20px;
+}
+
+.dispatch-stack {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.dispatch-divider {
+  height: 1px;
+  background: var(--rule);
+  margin: 6px 0;
+}
+
+.dispatch-row {
+  display: grid;
+  grid-template-columns: 1fr auto;
+  gap: 8px;
+}
+
+.dispatch-meta {
+  margin: 0;
+  font-family: var(--mono);
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.18em;
+  color: var(--faint);
+}
+
+#status-panel:not(:has(.run-status-chip)) { display: none; }
+#download-area:not(:has(.download-button)) { display: none; }
+
+#download-area {
+  border-top: 1px solid var(--rule);
+  padding: var(--container-pad);
+  background: var(--bg);
+}
+
+#status-panel {
+  min-height: 88px;
+  padding: 20px var(--container-pad);
+  border-bottom: 1px solid var(--rule);
+  background: var(--panel);
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 10px;
+}
+
+.rail-status-block #status-panel {
+  min-height: 0;
+  padding: 0;
+  border-bottom: 0;
+  background: transparent;
+}
+
+.run-status-chip {
+  display: inline-flex;
+  align-items: center;
+  min-height: 26px;
+  padding: 4px 10px;
+  border: 1px solid var(--ink);
+  background: var(--ink);
+  color: var(--bg);
+  font-family: var(--mono);
+  font-size: 10.5px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.16em;
+}
+
+.run-status-chip.is-live {
+  background: var(--bg);
+  color: var(--ink);
+  border-color: var(--ink);
+  position: relative;
+  padding-left: 22px;
+}
+
+.run-status-chip.is-live::before {
+  content: "";
+  position: absolute;
+  left: 10px;
+  top: 50%;
+  width: 6px;
+  height: 6px;
+  background: var(--ink);
+  transform: translateY(-50%);
+  animation: live-pulse 1.6s ease-in-out infinite;
+}
+
+@keyframes live-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.35; }
+}
+
+.validation-chip {
+  border-color: var(--rule-strong);
+  background: var(--bg);
+  color: var(--ink);
+}
+
+.run-metric {
+  display: inline-flex;
+  align-items: center;
+  min-height: 26px;
+  padding: 4px 10px;
+  border: 1px solid var(--rule);
+  color: var(--muted);
+  font-family: var(--mono);
+  font-size: 10.5px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.16em;
+}
+
+.run-summary {
+  flex-basis: 100%;
+  margin-top: 14px;
+  color: var(--muted);
+  font-family: var(--mono);
+  font-size: 11.5px;
+  line-height: 1.6;
+}
+
+.data-panel {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  border-bottom: 1px solid var(--rule);
+  padding: 0 var(--container-pad);
+  gap: 0;
+}
+
+.data-panel > * {
+  border-right: 1px solid var(--rule);
+}
+
+.data-panel > *:last-child {
+  border-right: 0;
+}
+
+.data-panel .block {
+  min-height: 240px;
+  background: var(--bg) !important;
+  border: 0 !important;
+  border-radius: 0 !important;
+}
+
+.chat-panel {
+  margin: 0;
+  padding: 22px var(--container-pad) 24px;
+  border-bottom: 1px solid var(--rule);
+  background: var(--panel-strong);
+}
+
+.chat-panel textarea {
+  min-height: 68px !important;
+}
+
+.chat-timeline {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  max-height: 460px;
+  overflow-y: auto;
+  padding: 4px 2px 14px;
+}
+
+.chat-empty {
+  color: var(--faint);
+  font-family: var(--mono);
+  font-size: 12px;
+  padding: 14px 0;
+}
+
+.chat-bubble {
+  width: min(760px, 92%);
+  border: 1px solid var(--rule);
+  background: var(--panel);
+  padding: 12px 14px;
+}
+
+.chat-bubble.is-user {
+  align-self: flex-end;
+  background: #f4f4f5;
+  color: #09090b;
+  border-color: #f4f4f5;
+}
+
+.chat-bubble.is-assistant {
+  align-self: flex-start;
+}
+
+.chat-label {
+  font-family: var(--mono);
+  font-size: 10px;
+  font-weight: 700;
+  text-transform: uppercase;
+  color: var(--muted);
+  margin-bottom: 7px;
+}
+
+.chat-bubble.is-user .chat-label {
+  color: #52525b;
+}
+
+.chat-text {
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  font-family: var(--sans);
+  font-size: 13.5px;
+  line-height: 1.55;
+}
+
+.download-button {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  width: 100%;
+  min-height: 56px;
+  padding: 0 20px;
+  border: 1px solid var(--ink);
+  background: var(--ink);
+  color: var(--bg) !important;
+  font-family: var(--mono);
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.18em;
+  text-decoration: none;
+  transition:
+    background 120ms ease,
+    color 120ms ease,
+    transform 120ms ease;
+}
+
+.download-button:hover {
+  background: var(--ink-soft);
+  color: var(--bg) !important;
+  transform: translateY(-1px);
+}
+
+.download-button:active {
+  transform: translateY(0);
+}
+
+.download-arrow {
+  font-family: var(--mono);
+  font-size: 10px;
+  letter-spacing: 0.2em;
+}
+
+.footer {
+  padding: 28px var(--container-pad);
+  border-top: 1px solid var(--rule);
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  font-family: var(--mono);
+  font-size: 10.5px;
+  text-transform: uppercase;
+  letter-spacing: 0.18em;
+  color: var(--faint);
+}
+
+.footer .footer-links {
+  display: flex;
+  gap: 20px;
+}
+
+.footer a {
+  color: var(--muted);
+  text-decoration: none;
+}
+
+.footer a:hover { color: var(--ink); }
+
+@media (max-width: 1100px) {
+  .workbench { grid-template-columns: var(--workbench-cols-md); }
+  .workbench .workbench-rail { display: none; }
+  .hero { grid-template-columns: 1fr; gap: 32px; align-items: start; }
+  .hero-side { padding-bottom: 0; }
+}
+
+@media (max-width: 880px) {
+  .workbench { grid-template-columns: 1fr; }
+  .workbench .workbench-input {
+    border-right: 0;
+    border-bottom: 1px solid var(--rule);
+  }
+  .workbench .workbench-dispatch {
+    border-right: 0;
+    border-bottom: 1px solid var(--rule);
+  }
+  .data-panel { grid-template-columns: 1fr; }
+  .data-panel > * { border-right: 0; border-bottom: 1px solid var(--rule); }
+  .data-panel > *:last-child { border-bottom: 0; }
+  .field-pair { grid-template-columns: 1fr; }
+  .hero { padding: 56px 20px 40px; }
+  .hero .hero-title {
+    font-size: clamp(34px, 11vw, 56px) !important;
+    line-height: 0.98 !important;
+  }
+  .hero .hero-subtext { font-size: 13px; }
+  .workbench-input,
+  .workbench-dispatch,
+  .workbench-rail { padding: 28px 20px; }
+  .topbar {
+    padding: 0 20px;
+    height: auto;
+    min-height: 64px;
+    flex-wrap: wrap;
+    gap: 6px 12px;
+    padding-top: 12px;
+    padding-bottom: 12px;
+  }
+  .topbar .wordmark { font-size: 10px; }
+  .topbar .topbar-meta { display: none; }
+  #status-bar { top: 12px; right: 20px; }
+  .footer { padding: 20px; flex-direction: column; gap: 12px; align-items: flex-start; }
+  .gradio-container { padding: 0 20px !important; }
+}
+
+@media (max-width: 420px) {
+  .hero .hero-title { font-size: 30px !important; }
+  .hero { padding: 40px 16px 28px; }
+  .workbench-input,
+  .workbench-dispatch,
+  .workbench-rail { padding: 20px 16px; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *:before,
+  *:after {
+    transition: none !important;
+    animation: none !important;
+  }
+}
+"""
+
+
+def build_app(service: ArenaService | None = None) -> gr.Blocks:
+    arena = GradioArena(service)
+
+    with gr.Blocks(
+        title="Backyard Demo Builder",
+        fill_width=True,
+        elem_id="run-shell",
+    ) as demo:
+        state = gr.State(UiState())
+        gr.HTML(
+            '<link rel="preconnect" href="https://fonts.googleapis.com">'
+            '<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>'
+            '<link href="https://fonts.googleapis.com/css2?family=Geist:wght@300;400;500;600;700;800;900&family=IBM+Plex+Mono:wght@300;400;500;600;700&display=swap" rel="stylesheet">'
+            f"<style>{CSS}</style>"
+        )
+
+        status_bar = gr.HTML("", elem_id="status-bar")
+
+        gr.HTML(TOPBAR_HTML)
+
+        gr.HTML(HERO_HTML)
+
+        with gr.Row(elem_classes=["workbench"]):
+            with gr.Column(scale=2, min_width=320, elem_classes=["workbench-input"]):
+                with gr.Column(elem_classes=["field-stack"]):
+                    demo_template = gr.Dropdown(
+                        label="Demo Template",
+                        choices=template_choices(),
+                        value=template_by_label("real_estate_followup_crm").label,
+                        interactive=True,
+                    )
+                    run_prompt = gr.Textbox(
+                        label="Person + Problem",
+                        lines=9,
+                        placeholder="Describe the real person, their workflow, and the tiny demo to build.",
+                        value=DEFAULT_BACKYARD_PROMPT,
+                    )
+                    with gr.Row(elem_classes=["field-pair"]):
+                        run_criteria = gr.Textbox(
+                            label="What Makes This Useful",
+                            lines=4,
+                            placeholder="One criterion per line",
+                            value=DEFAULT_BACKYARD_CRITERIA,
+                        )
+                        run_tests = gr.Textbox(
+                            label="Demo Checks",
+                            lines=4,
+                            placeholder="python -m py_compile app.py",
+                            value=DEFAULT_BACKYARD_CHECKS,
+                        )
+                    with gr.Row(elem_classes=["field-pair"]):
+                        model_provider = gr.Dropdown(
+                            label="Model Provider",
+                            choices=["openrouter", "gemini", "nebius", "huggingface", "custom", "local"],
+                            value="openrouter",
+                            interactive=True,
+                        )
+                        model_id = gr.Dropdown(
+                            label="Model",
+                            choices=[],
+                            value=None,
+                            interactive=True,
+                        )
+                    with gr.Row(elem_classes=["field-pair"]):
+                        model_api_key = gr.Textbox(
+                            label="API Key",
+                            type="password",
+                            placeholder="Required for hosted providers. Not stored.",
+                        )
+                        model_base_url = gr.Textbox(
+                            label="API Endpoint",
+                            placeholder="Optional OpenAI-compatible /v1 endpoint",
+                        )
+                    with gr.Row(elem_classes=["field-pair"]):
+                        list_models_btn = gr.Button("Refresh models", variant="secondary")
+                        model_catalog_json = gr.JSON(label="Allowed Models", visible=False)
+            with gr.Column(scale=1, min_width=320, elem_classes=["workbench-dispatch"]):
+                gr.HTML('<p class="dispatch-meta">Dispatch</p>')
+                with gr.Column(elem_classes=["dispatch-stack"]):
+                    run_btn = gr.Button("Build demo package", variant="primary", elem_id="start-run-btn")
+                    run_cancel_btn = gr.Button("Cancel build", variant="secondary", elem_id="cancel-run-btn")
+                with gr.Column(elem_classes=["dispatch-stack"]):
+                    refresh_btn = gr.Button("Refresh", variant="secondary", elem_id="refresh-run-btn")
+                token = gr.Textbox(label="Run Token", interactive=False, visible=False)
+            with gr.Column(scale=1, min_width=320, elem_classes=["workbench-rail"]):
+                gr.HTML(RAIL_HTML)
+                with gr.Column(elem_classes=["rail-block"]):
+                    gr.HTML(
+                        """
+                        <p class="dispatch-meta">Mom Test</p>
+                        <div class="rail-grid">
+                          <div class="rail-row"><span class="rail-label">Tester</span><span class="rail-value">Mom · real-estate agent</span></div>
+                          <div class="rail-row"><span class="rail-label">Proof</span><span class="rail-value">field_notes.md</span></div>
+                          <div class="rail-row"><span class="rail-label">Question</span><span class="rail-value">Scrap or scale?</span></div>
+                        </div>
+                        """
+                    )
+                with gr.Column(elem_classes=["rail-block", "rail-status-block"]):
+                    gr.HTML('<p class="dispatch-meta">Run state</p>')
+                    status_panel = gr.HTML("", elem_id="status-panel")
+
+        with gr.Column(elem_classes=["chat-panel"]):
+            gr.HTML('<p class="dispatch-meta">Conversation</p>')
+            chat_panel = gr.HTML("", elem_id="chat-panel")
+            with gr.Row(elem_classes=["dispatch-row"]):
+                run_message = gr.Textbox(
+                    label="Follow-up",
+                    lines=2,
+                    placeholder="Add context or ask for an update while this run is active.",
+                    scale=4,
+                )
+                send_message_btn = gr.Button("Send", variant="secondary", elem_id="send-message-btn", scale=1)
+            gr.HTML('<p class="dispatch-meta">Real-person feedback</p>')
+            with gr.Row(elem_classes=["field-pair"]):
+                feedback_tester = gr.Textbox(
+                    label="Tester",
+                    value="Mom",
+                    lines=1,
+                    placeholder="Who tested the generated demo?",
+                )
+                feedback_decision = gr.Dropdown(
+                    label="Decision",
+                    choices=["scale", "scrap", "iterate"],
+                    value="iterate",
+                    interactive=True,
+                )
+            with gr.Row(elem_classes=["field-pair"]):
+                feedback_quote = gr.Textbox(
+                    label="Direct Quote",
+                    lines=2,
+                    placeholder="One exact quote from the tester.",
+                )
+                feedback_notes = gr.Textbox(
+                    label="Missing Before Real App",
+                    lines=2,
+                    placeholder="What must change before scaling?",
+                )
+            feedback_btn = gr.Button("Record feedback", variant="secondary")
+
+        with gr.Row(elem_classes=["data-panel"]):
+            with gr.Column():
+                tasks = gr.Dataframe(
+                    headers=["task_id", "title", "status"],
+                    label="Tasks",
+                    interactive=False,
+                )
+            with gr.Column():
+                events = gr.Dataframe(
+                    headers=["created_at", "message"],
+                    label="Events",
+                    interactive=False,
+                )
+
+        gr.HTML('<div id="download-divider" hidden></div>')
+        download_link = gr.HTML("", elem_id="download-area")
+
+        gr.HTML(FOOTER_HTML)
+
+        run_json = gr.JSON(label="Run Detail", visible=False)
+        zerogpu_probe = gr.Button("ZeroGPU", visible=False)
+        zerogpu_status = gr.Textbox(visible=False)
+
+        outputs = [state, status_bar, run_json, tasks, events, token, download_link, status_panel, chat_panel]
+        zerogpu_probe.click(zerogpu_ready_marker, [], zerogpu_status)
+        run_btn.click(
+            arena.create_run,
+            [run_prompt, run_criteria, run_tests, model_provider, model_id, model_api_key, model_base_url],
+            outputs,
+        )
+        list_models_btn.click(
+            arena.refresh_models,
+            [model_provider, model_api_key, model_base_url],
+            [model_id, model_catalog_json],
+        )
+        demo_template.change(
+            arena.apply_template,
+            [demo_template],
+            [run_prompt, run_criteria, run_tests],
+        )
+        run_cancel_btn.click(arena.cancel_run, [state], outputs)
+        send_message_btn.click(arena.send_message, [state, run_message], outputs)
+        feedback_btn.click(
+            arena.record_feedback,
+            [state, feedback_tester, feedback_quote, feedback_decision, feedback_notes],
+            outputs,
+        )
+        refresh_btn.click(arena.refresh, [state], outputs)
+
+    return demo

arena/gradio_markup.py

@@ -0,0 +1,68 @@
+"""Static HTML fragments for the Gradio Run shell."""
+
+from __future__ import annotations
+
+
+TOPBAR_HTML = """
+<header class="topbar" role="banner">
+  <p class="wordmark"><span class="wordmark-dot" aria-hidden="true"></span>Backyard Demo Builder</p>
+  <p class="topbar-meta">Tiny demo · Real person · ≤32B model</p>
+</header>
+"""
+
+
+HERO_HTML = """
+<section class="hero" aria-label="Backyard demo builder overview">
+  <div class="hero-main">
+    <h1 class="hero-title">
+      <span class="line">Build the tiny demo first.</span>
+      <span class="line">Scrap or scale after use.</span>
+    </h1>
+    <p class="hero-subtext">
+      Turn a real person's problem into a runnable Gradio skeleton, a handoff spec, and field notes before paying for full software.
+    </p>
+  </div>
+  <aside class="hero-side">
+    <ul class="hero-marks">
+      <li><span class="mark-num">01</span><span class="mark-text">Start with one real person and one real workflow.</span></li>
+      <li><span class="mark-num">02</span><span class="mark-text">Generate a cheap Gradio demo package.</span></li>
+      <li><span class="mark-num">03</span><span class="mark-text">Test it with the person before scaling.</span></li>
+      <li><span class="mark-num">04</span><span class="mark-text">Export field notes for the hackathon submission.</span></li>
+    </ul>
+  </aside>
+</section>
+"""
+
+
+RAIL_HTML = """
+<div class="rail-block">
+  <p class="dispatch-meta">Telemetry</p>
+  <div class="rail-grid">
+    <div class="rail-row"><span class="rail-label">Provider</span><span class="rail-value">Daytona</span></div>
+    <div class="rail-row"><span class="rail-label">Sandbox</span><span class="rail-value">Ephemeral</span></div>
+    <div class="rail-row"><span class="rail-label">Template</span><span class="rail-value">Real Estate CRM</span></div>
+    <div class="rail-row"><span class="rail-label">Constraint</span><span class="rail-value">≤32B model</span></div>
+    <div class="rail-row"><span class="rail-label">Evidence</span><span class="rail-value">Field notes</span></div>
+  </div>
+</div>
+<div class="rail-block">
+  <p class="dispatch-meta">Keyboard</p>
+  <div class="rail-grid">
+    <div class="rail-row"><span class="rail-label">Start</span><span class="rail-kbd">Click &middot; Build demo</span></div>
+    <div class="rail-row"><span class="rail-label">Cancel</span><span class="rail-kbd">Click &middot; Cancel build</span></div>
+    <div class="rail-row"><span class="rail-label">Refresh</span><span class="rail-kbd">Click &middot; Refresh</span></div>
+  </div>
+</div>
+"""
+
+
+FOOTER_HTML = """
+<footer class="footer" role="contentinfo">
+  <span>Backyard Demo Builder</span>
+  <div class="footer-links">
+    <span>Real person</span>
+    <span>Small model</span>
+    <span>Demo first</span>
+  </div>
+</footer>
+"""

arena/gradio_presenter.py

@@ -0,0 +1,142 @@
+"""Presentation helpers for the prompt-first Gradio Run shell."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from html import escape
+from typing import Any
+
+from .gradio_run import run_event_rows, run_summary, run_task_rows
+from .run_models import RunView
+
+
+LIVE_STATUSES = ("planning", "working", "validating")
+
+
+@dataclass(frozen=True)
+class UiState:
+    role: str = ""
+    token: str = ""
+    run_id: str = ""
+
+
+RunOutputs = tuple[UiState, str, dict[str, Any], list[list[Any]], list[list[Any]], str, str, str, str]
+
+
+def run_outputs(state: UiState, run: RunView) -> RunOutputs:
+    summary = run_summary(run)
+    download_parts: list[str] = []
+    if summary.get("codebase_zip_url"):
+        download_parts.append(
+            '<a href="{}" target="_blank" class="download-button">'
+            '<span>Download demo package</span>'
+            '<span class="download-arrow" aria-hidden="true">GET</span>'
+            '</a>'
+            .format(summary["codebase_zip_url"])
+        )
+    download_parts.append(
+        f'<a href="/runs/{run.id}/field_notes.md" target="_blank" class="download-button">'
+        '<span>Download field notes</span>'
+        '<span class="download-arrow" aria-hidden="true">MD</span>'
+        '</a>'
+    )
+    download_parts.append(
+        f'<a href="/runs/{run.id}/submission.md" target="_blank" class="download-button">'
+        '<span>Download submission pack</span>'
+        '<span class="download-arrow" aria-hidden="true">MD</span>'
+        '</a>'
+    )
+    download_parts.append(
+        f'<a href="/runs/{run.id}/space_README.md" target="_blank" class="download-button">'
+        '<span>Download Space README</span>'
+        '<span class="download-arrow" aria-hidden="true">HF</span>'
+        '</a>'
+    )
+    download_parts.append(
+        f'<a href="/runs/{run.id}/trace.json" target="_blank" class="download-button">'
+        '<span>Download trace</span>'
+        '<span class="download-arrow" aria-hidden="true">JSON</span>'
+        '</a>'
+    )
+    download_html = "".join(download_parts)
+
+    status_panel = status_bar(summary)
+    if run.summary:
+        status_panel += f'<div class="run-summary">{escape(run.summary[:500])}</div>'
+
+    return (
+        state,
+        status_bar(summary),
+        summary,
+        run_task_rows(run),
+        run_event_rows(run),
+        "",
+        download_html,
+        status_panel,
+        chat_timeline(summary),
+    )
+
+
+def empty_outputs(state: UiState, message: str) -> RunOutputs:
+    notice_html = (
+        '<span class="run-status-chip validation-chip">Notice</span>'
+        f'<span class="run-metric">{escape(message)}</span>'
+    )
+    chat_html = f'<div class="chat-empty">{escape(message)}</div>'
+    return (state, notice_html, {}, [], [], "", "", notice_html, chat_html)
+
+
+def status_bar(run_summary: dict[str, Any]) -> str:
+    parts = [_status_badge(run_summary.get("status", "queued"))]
+
+    tasks = run_summary.get("tasks", [])
+    if tasks:
+        completed = sum(1 for task in tasks if task.get("status") == "completed")
+        parts.append(f'<span class="run-metric">{completed}/{len(tasks)} tasks</span>')
+
+    archive = run_summary.get("codebase_archive")
+    if archive:
+        size_kb = archive.get("size_bytes", 0) / 1024
+        parts.append(
+            f'<span class="run-metric">'
+            f'{archive.get("file_count", 0)} files ({size_kb:.1f} KB)</span>'
+        )
+
+    report = run_summary.get("validation_report")
+    if report:
+        label = "PASSED" if report.get("passed") else "FAILED"
+        cls = "run-status-chip validation-chip" + (" is-live" if not report.get("passed") else "")
+        parts.append(f'<span class="{cls}">{label}</span>')
+
+    return "".join(parts)
+
+
+def chat_timeline(run_summary: dict[str, Any]) -> str:
+    if not run_summary:
+        return '<div class="chat-empty">Start a run to open the conversation.</div>'
+
+    bubbles = [("user", "You", str(run_summary.get("prompt", "")))]
+    for event in run_summary.get("events", []):
+        message = str(event.get("message", ""))
+        role = "user" if message.startswith("User: ") else "assistant"
+        label = "You" if role == "user" else "Workbench"
+        bubbles.append((role, label, message.removeprefix("User: ")))
+
+    summary = str(run_summary.get("summary", ""))
+    if summary:
+        bubbles.append(("assistant", "Workbench", summary))
+
+    body = "".join(
+        f'<div class="chat-bubble is-{role}">'
+        f'<div class="chat-label">{escape(label)}</div>'
+        f'<div class="chat-text">{escape(text)[:1200]}</div>'
+        "</div>"
+        for role, label, text in bubbles
+        if text
+    )
+    return f'<div class="chat-timeline">{body}</div>'
+
+
+def _status_badge(status: str) -> str:
+    cls = "run-status-chip is-live" if status in LIVE_STATUSES else "run-status-chip"
+    return f'<span class="{cls}">{status}</span>'

arena/gradio_run.py

@@ -0,0 +1,74 @@
+"""Gradio helpers for prompt-first Runs."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .model_catalog import ModelProviderConfig
+from .backyard_templates import REAL_ESTATE_FOLLOWUP
+from .run_models import RunRequest, RunView
+from .validation_models import Criteria
+
+
+DEFAULT_BACKYARD_PROMPT = REAL_ESTATE_FOLLOWUP.prompt
+DEFAULT_BACKYARD_CRITERIA = REAL_ESTATE_FOLLOWUP.criteria
+DEFAULT_BACKYARD_CHECKS = REAL_ESTATE_FOLLOWUP.checks
+
+
+def run_request_from_text(
+    prompt: str,
+    criteria_text: str,
+    user_tests_text: str,
+    provider: str = "openrouter",
+    model: str | None = "",
+    api_key: str | None = "",
+    base_url: str | None = "",
+) -> RunRequest:
+    model_provider = None
+    model = model or ""
+    api_key = api_key or ""
+    base_url = base_url or ""
+    if model.strip() or api_key.strip() or base_url.strip() or (provider and provider != "openrouter"):
+        model_provider = ModelProviderConfig(
+            provider=provider or "openrouter",
+            model=model.strip(),
+            api_key=api_key.strip() or None,
+            base_url=base_url.strip(),
+        )
+    return RunRequest(
+        prompt=prompt.strip(),
+        criteria=[Criteria(text=item) for item in split_lines(criteria_text)],
+        user_tests=split_lines(user_tests_text),
+        model_provider=model_provider,
+    )
+
+
+def run_summary(run: RunView) -> dict[str, Any]:
+    return {
+        "id": run.id,
+        "status": run.status,
+        "prompt": run.prompt,
+        "criteria": [item.model_dump() for item in run.criteria],
+        "user_tests": run.user_tests,
+        "tasks": [task.model_dump() for task in run.tasks],
+        "events": [event.model_dump(mode="json") for event in run.events],
+        "artifacts": [artifact.model_dump(mode="json") for artifact in run.artifacts],
+        "validation_checks": [check.model_dump() for check in run.validation_checks],
+        "validation_report": None if run.validation_report is None else run.validation_report.model_dump(mode="json"),
+        "codebase_archive": None if run.codebase_archive is None else run.codebase_archive.model_dump(),
+        "model_provider": None if run.model_provider is None else run.model_provider.model_dump(),
+        "codebase_zip_url": "" if run.codebase_archive is None else f"/runs/{run.id}/codebase.zip",
+        "summary": run.summary,
+    }
+
+
+def run_task_rows(run: RunView) -> list[list[Any]]:
+    return [[task.id, task.title, task.status] for task in run.tasks]
+
+
+def run_event_rows(run: RunView) -> list[list[Any]]:
+    return [[event.created_at.isoformat(), event.message] for event in run.events]
+
+
+def split_lines(text: str) -> list[str]:
+    return [line.strip() for line in text.replace(",", "\n").splitlines() if line.strip()]

arena/harness.py

@@ -0,0 +1,242 @@
+"""Agent Swarm Harness for exercising the Run pipeline."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import tempfile
+from pathlib import Path
+from typing import Any, Literal
+from uuid import uuid4
+
+from pydantic import BaseModel
+
+from .agent import AgentSession, create_session
+from .codebase_archive import LocalCodebaseArchiveStore
+from .run_models import RunRequest, RunView
+from .run_store import InMemoryRunStore, RunAccessView
+from .service import ArenaService
+from .swarm_runtime import SwarmRuntime
+from .validation_models import Criteria
+from .validator_executor import create_validator_executor
+from .validator_graph import DeterministicRubricReviewer, ValidatorGraph
+
+
+DEFAULT_PROMPT = "Build a tiny Python project with a README."
+HarnessMode = Literal["swarm", "live"]
+
+
+class HarnessResult(BaseModel):
+    mode: HarnessMode
+    token: str
+    run: RunView
+    zip_path: str | None = None
+
+
+class ScriptedSwarmAgent:
+    """DeepAgent-compatible scripted agent for exercising SwarmRuntime locally."""
+
+    def __init__(self, backend: Any, workspace_dir: str) -> None:
+        self.backend = backend
+        self.workspace_dir = workspace_dir.rstrip("/")
+        self.invocations: list[dict[str, Any]] = []
+
+    def invoke(self, payload: dict[str, Any], config: dict[str, Any]) -> dict[str, Any]:
+        self.invocations.append({"payload": payload, "config": config})
+        run_id = str(config.get("configurable", {}).get("run_id", "unknown-run"))
+        run_context = _backend_read_text(self.backend, "/context/run.md")
+        self._write_codebase(run_id, run_context)
+        return {
+            "messages": [
+                {
+                    "role": "assistant",
+                    "content": (
+                        "Scripted swarm built a harness Python codebase "
+                        f"in {self.workspace_dir}."
+                    ),
+                }
+            ]
+        }
+
+    def _write_codebase(self, run_id: str, run_context: str) -> None:
+        manifest = {
+            "run_id": run_id,
+            "workspace_dir": self.workspace_dir,
+            "agent_invocations": len(self.invocations),
+        }
+        self.backend.write(
+            f"{self.workspace_dir}/README.md",
+            (
+                "# Harness Codebase\n\n"
+                "Generated by the scripted Agent Swarm Harness through SwarmRuntime.\n\n"
+                "## Run Context\n\n"
+                "```markdown\n"
+                f"{run_context.strip()}\n"
+                "```\n"
+            ),
+        )
+        self.backend.write(
+            f"{self.workspace_dir}/harness_result.json",
+            json.dumps(manifest, indent=2, sort_keys=True),
+        )
+        self.backend.write(
+            f"{self.workspace_dir}/pyproject.toml",
+            "[project]\nname = \"harness-codebase\"\nversion = \"0.1.0\"\n",
+        )
+        self.backend.write(
+            f"{self.workspace_dir}/app.py",
+            "def main() -> str:\n    return \"agent swarm harness\"\n",
+        )
+
+
+def create_harness_service(*, archive_root: Path | None = None) -> ArenaService:
+    archive_store = LocalCodebaseArchiveStore(root_dir=archive_root)
+    executor = create_validator_executor(archive_store=archive_store, provider="local")
+    validator = ValidatorGraph(
+        executor=executor,
+        rubric_reviewer=DeterministicRubricReviewer(),
+        rubric_enabled=True,
+    )
+    return ArenaService(
+        run_store=InMemoryRunStore(),
+        swarm_runtime=SwarmRuntime(
+            session_factory=_scripted_session_factory(),
+            archive_store=archive_store,
+        ),
+        archive_store=archive_store,
+        validator_graph=validator,
+    )
+
+
+def create_live_harness_service(*, archive_root: Path | None = None) -> ArenaService:
+    archive_store = LocalCodebaseArchiveStore(root_dir=archive_root)
+    executor = create_validator_executor(archive_store=archive_store, provider="local")
+    validator = ValidatorGraph(
+        executor=executor,
+        rubric_reviewer=DeterministicRubricReviewer(),
+        rubric_enabled=True,
+    )
+    return ArenaService(
+        run_store=InMemoryRunStore(),
+        swarm_runtime=SwarmRuntime(
+            session_factory=create_session,
+            archive_store=archive_store,
+        ),
+        archive_store=archive_store,
+        validator_graph=validator,
+    )
+
+
+def run_harness(
+    *,
+    prompt: str = DEFAULT_PROMPT,
+    criteria: list[str] | None = None,
+    user_tests: list[str] | None = None,
+    archive_root: Path | None = None,
+    output_dir: Path | None = None,
+    mode: HarnessMode = "swarm",
+) -> HarnessResult:
+    service = _service_for_mode(mode, archive_root=archive_root)
+    request = RunRequest(
+        prompt=prompt,
+        criteria=[Criteria(text=item) for item in criteria or []],
+        user_tests=user_tests or [],
+    )
+    access = service.create_run(request)
+    zip_path = _write_zip(service, access, output_dir) if output_dir is not None else None
+    return HarnessResult(
+        mode=mode,
+        token=access.token,
+        run=service.get_run(access.run.id),
+        zip_path=str(zip_path) if zip_path is not None else None,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Run the Agent Swarm Harness")
+    parser.add_argument(
+        "--mode",
+        choices=["swarm", "live"],
+        default="swarm",
+        help=(
+            "swarm uses SwarmRuntime with a scripted local agent; "
+            "live uses the real DeepAgent session factory."
+        ),
+    )
+    parser.add_argument("--prompt", default=DEFAULT_PROMPT)
+    parser.add_argument("--criteria", action="append", default=[])
+    parser.add_argument("--test", action="append", default=[], dest="user_tests")
+    parser.add_argument("--output-dir", type=Path)
+    args = parser.parse_args(argv)
+
+    with tempfile.TemporaryDirectory(prefix="agent-harness-archives-") as tmp:
+        result = run_harness(
+            prompt=args.prompt,
+            criteria=args.criteria,
+            user_tests=args.user_tests,
+            archive_root=Path(tmp),
+            output_dir=args.output_dir,
+            mode=args.mode,
+        )
+        print(json.dumps(result.model_dump(mode="json"), sort_keys=True, default=str))
+    return 0
+
+
+def _write_zip(service: ArenaService, access: RunAccessView, output_dir: Path) -> Path:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    payload = service.get_run_codebase_zip(access.run.id)
+    destination = output_dir / payload.filename
+    destination.write_bytes(payload.data)
+    return destination
+
+
+def _service_for_mode(mode: HarnessMode, *, archive_root: Path | None) -> ArenaService:
+    if mode == "live":
+        return create_live_harness_service(archive_root=archive_root)
+    return create_harness_service(archive_root=archive_root)
+
+
+def _scripted_session_factory():
+    def factory(thread_id: str | None = None) -> AgentSession:
+        from deepagents.backends import CompositeBackend, FilesystemBackend, LocalShellBackend
+
+        thread_id_value = thread_id or uuid4().hex
+        sandbox_root = Path(tempfile.mkdtemp(prefix="agent-swarm-harness-"))
+        context_root = Path(tempfile.mkdtemp(prefix="agent-swarm-harness-context-"))
+        workspace_dir = "/workspace"
+        (sandbox_root / "workspace").mkdir(parents=True, exist_ok=True)
+        (context_root / "context").mkdir(parents=True, exist_ok=True)
+
+        executable_backend = LocalShellBackend(
+            root_dir=sandbox_root,
+            virtual_mode=True,
+            inherit_env=False,
+        )
+        executable_backend._workspace_dir = workspace_dir
+        context_backend = FilesystemBackend(root_dir=context_root, virtual_mode=True)
+        backend = CompositeBackend(
+            default=executable_backend,
+            routes={"/context/": context_backend},
+        )
+        backend._workspace_dir = workspace_dir
+        executable_backend.execute(f"mkdir -p {workspace_dir}")
+        return AgentSession(
+            thread_id=thread_id_value,
+            provider="harness",
+            backend=backend,
+            agent=ScriptedSwarmAgent(backend, workspace_dir),
+            workspace_dir=workspace_dir,
+            context_root=context_root,
+        )
+
+    return factory
+
+
+def _backend_read_text(backend: Any, path: str) -> str:
+    result = backend.read(path)
+    file_data = getattr(result, "file_data", None) or {}
+    return str(file_data.get("content", ""))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

arena/model_catalog.py

@@ -0,0 +1,308 @@
+"""Provider model catalogs normalized for Run setup."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic import BaseModel, Field, SecretStr, field_validator
+
+
+DEFAULT_OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+DEFAULT_NEBIUS_BASE_URL = "https://api.tokenfactory.nebius.com/v1"
+DEFAULT_HF_ROUTER_BASE_URL = "https://router.huggingface.co/v1"
+DEFAULT_GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
+DEFAULT_LOCAL_MODEL = "unsloth/gemma-4-12B-it-qat-GGUF"
+MAX_MODEL_PARAMETERS_B = 32.0
+
+
+class ModelProviderSelection(BaseModel):
+    provider: str = "openrouter"
+    model: str = ""
+    base_url: str = ""
+
+
+class ModelProviderConfig(ModelProviderSelection):
+    api_key: SecretStr | None = None
+
+    @field_validator("provider")
+    @classmethod
+    def normalize_provider(cls, value: str) -> str:
+        return value.strip().lower().replace("_", "-")
+
+    def public_selection(self) -> ModelProviderSelection | None:
+        if not self.provider and not self.model and not self.base_url:
+            return None
+        return ModelProviderSelection(
+            provider=self.provider,
+            model=self.model.strip(),
+            base_url=self.base_url.strip(),
+        )
+
+    def key_value(self) -> str:
+        return self.api_key.get_secret_value().strip() if self.api_key else ""
+
+
+class ProviderModel(BaseModel):
+    id: str = Field(min_length=1)
+    label: str = ""
+    provider: str
+    context_length: int | None = None
+    supports_tools: bool | None = None
+    supports_structured_output: bool | None = None
+    input_price: float | None = None
+    output_price: float | None = None
+    parameter_count_b: float | None = None
+    eligible: bool = True
+    status: str = "unknown"
+
+
+@dataclass
+class _CacheEntry:
+    created_at: float
+    models: list[ProviderModel]
+
+
+class ModelCatalog:
+    def __init__(self, *, ttl_seconds: float = 600, timeout_seconds: float = 10) -> None:
+        self._ttl_seconds = ttl_seconds
+        self._timeout_seconds = timeout_seconds
+        self._cache: dict[str, _CacheEntry] = {}
+
+    def list_models(self, config: ModelProviderConfig | None = None) -> list[ProviderModel]:
+        config = config or ModelProviderConfig()
+        key = self._cache_key(config)
+        cached = self._cache.get(key)
+        if cached and time.time() - cached.created_at < self._ttl_seconds:
+            return cached.models
+        models = self._fetch(config)
+        self._cache[key] = _CacheEntry(created_at=time.time(), models=models)
+        return models
+
+    def refresh_models(self, config: ModelProviderConfig | None = None) -> list[ProviderModel]:
+        config = config or ModelProviderConfig()
+        self.clear(config)
+        if config.provider == "local":
+            _clear_local_runtime_cache()
+        return self.list_models(config)
+
+    def clear(self, config: ModelProviderConfig | None = None) -> None:
+        if config is None:
+            self._cache.clear()
+            return
+        self._cache.pop(self._cache_key(config), None)
+
+    def _fetch(self, config: ModelProviderConfig) -> list[ProviderModel]:
+        provider = config.provider
+        if provider == "openrouter":
+            return self._openai_compatible_models(
+                provider=provider,
+                base_url=config.base_url or DEFAULT_OPENROUTER_BASE_URL,
+                api_key=config.key_value(),
+            )
+        if provider == "nebius":
+            return self._openai_compatible_models(
+                provider=provider,
+                base_url=config.base_url or DEFAULT_NEBIUS_BASE_URL,
+                api_key=config.key_value(),
+            )
+        if provider in {"huggingface", "hf"}:
+            return self._openai_compatible_models(
+                provider="huggingface",
+                base_url=config.base_url or DEFAULT_HF_ROUTER_BASE_URL,
+                api_key=config.key_value(),
+            )
+        if provider == "gemini":
+            return self._gemini_models(config)
+        if provider == "local":
+            return self._local_models(config)
+        if provider in {"custom", "openai-compatible"}:
+            return self._custom_models(config)
+        raise ValueError(f"Unsupported model provider: {provider}")
+
+    def _local_models(self, config: ModelProviderConfig) -> list[ProviderModel]:
+        if config.base_url:
+            return self._custom_models(config)
+        model_id = config.model.strip() or DEFAULT_LOCAL_MODEL
+        return [
+            _with_parameter_eligibility(
+                ProviderModel(
+                    id=model_id,
+                    label=model_id,
+                    provider="local",
+                    status="available",
+                )
+            )
+        ]
+
+    def _custom_models(self, config: ModelProviderConfig) -> list[ProviderModel]:
+        if not config.base_url:
+            return []
+        try:
+            models = self._openai_compatible_models(
+                provider=config.provider,
+                base_url=config.base_url,
+                api_key=config.key_value(),
+            )
+        except Exception:
+            models = []
+        if models:
+            return models
+        return []
+
+    def _openai_compatible_models(self, *, provider: str, base_url: str, api_key: str) -> list[ProviderModel]:
+        payload = self._get_json(_join_url(base_url, "models"), api_key=api_key)
+        rows = payload.get("data", payload if isinstance(payload, list) else [])
+        return [_provider_model_from_openai_row(provider, row) for row in rows if isinstance(row, dict) and row.get("id")]
+
+    def _gemini_models(self, config: ModelProviderConfig) -> list[ProviderModel]:
+        base_url = config.base_url or DEFAULT_GEMINI_BASE_URL
+        query = {"pageSize": "1000"}
+        if config.key_value():
+            query["key"] = config.key_value()
+        url = _join_url(base_url, "models") + "?" + urllib.parse.urlencode(query)
+        payload = self._get_json(url, api_key="" if config.key_value() else "")
+        rows = payload.get("models", [])
+        models: list[ProviderModel] = []
+        for row in rows:
+            if not isinstance(row, dict):
+                continue
+            actions = row.get("supportedGenerationMethods") or row.get("supported_actions") or []
+            if actions and "generateContent" not in actions:
+                continue
+            model_id = str(row.get("name", "")).removeprefix("models/")
+            if not model_id:
+                continue
+            models.append(
+                _with_parameter_eligibility(
+                    ProviderModel(
+                        id=model_id,
+                        label=str(row.get("displayName") or model_id),
+                        provider="gemini",
+                        context_length=row.get("inputTokenLimit"),
+                        status="available",
+                    ),
+                    row.get("description"),
+                )
+            )
+        return models
+
+    def _get_json(self, url: str, *, api_key: str) -> dict[str, Any]:
+        headers = {"Accept": "application/json"}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        req = urllib.request.Request(url, headers=headers)
+        with urllib.request.urlopen(req, timeout=self._timeout_seconds) as response:
+            return json.loads(response.read().decode("utf-8"))
+
+    def _cache_key(self, config: ModelProviderConfig) -> str:
+        key_hash = hashlib.sha256(config.key_value().encode("utf-8")).hexdigest()[:16] if config.key_value() else "nokey"
+        model_key = config.model.strip() if config.provider == "local" and not config.base_url.strip() else ""
+        return "|".join([config.provider, config.base_url.strip(), key_hash, model_key])
+
+
+def _provider_model_from_openai_row(provider: str, row: dict[str, Any]) -> ProviderModel:
+    provider_rows = row.get("providers") or []
+    live_provider = next((item for item in provider_rows if item.get("status") == "live"), None)
+    metadata = live_provider if isinstance(live_provider, dict) else row
+    pricing = metadata.get("pricing") or row.get("pricing") or {}
+    return _with_parameter_eligibility(
+        ProviderModel(
+            id=str(row["id"]),
+            label=str(row.get("name") or row["id"]),
+            provider=provider,
+            context_length=metadata.get("context_length") or row.get("context_length"),
+            supports_tools=metadata.get("supports_tools"),
+            supports_structured_output=metadata.get("supports_structured_output"),
+            input_price=_float_or_none(pricing.get("input") if isinstance(pricing, dict) else None),
+            output_price=_float_or_none(pricing.get("output") if isinstance(pricing, dict) else None),
+            status=str(metadata.get("status") or "available"),
+        ),
+        row.get("canonical_slug"),
+        row.get("hugging_face_id"),
+        row.get("description"),
+        metadata.get("description") if isinstance(metadata, dict) else None,
+    )
+
+
+def eligible_models(models: list[ProviderModel]) -> list[ProviderModel]:
+    return [model for model in models if model.eligible]
+
+
+def _clear_local_runtime_cache() -> None:
+    try:
+        from .local_model import clear_local_model_cache
+    except Exception:
+        return
+    clear_local_model_cache()
+
+
+def model_id_is_eligible(model_id: str) -> bool:
+    parameter_count_b = _parameter_count_b(model_id)
+    return parameter_count_b is not None and parameter_count_b <= MAX_MODEL_PARAMETERS_B
+
+
+def model_id_parameter_count_b(model_id: str) -> float | None:
+    return _parameter_count_b(model_id)
+
+
+def _with_parameter_eligibility(model: ProviderModel, *metadata_texts: Any) -> ProviderModel:
+    parameter_count_b = _first_parameter_count_b(model.id, model.label, *metadata_texts)
+    if parameter_count_b is None:
+        return model.model_copy(update={"parameter_count_b": None, "eligible": False, "status": "unknown_parameters"})
+    return model.model_copy(
+        update={
+            "parameter_count_b": parameter_count_b,
+            "eligible": parameter_count_b <= MAX_MODEL_PARAMETERS_B,
+            "status": "available" if parameter_count_b <= MAX_MODEL_PARAMETERS_B else "too_large",
+        }
+    )
+
+
+def _first_parameter_count_b(*texts: Any) -> float | None:
+    for text in texts:
+        if text is None:
+            continue
+        count = _parameter_count_b(str(text))
+        if count is not None:
+            return count
+    return None
+
+
+def _parameter_count_b(text: str) -> float | None:
+    import re
+
+    lowered = text.lower()
+    # Matches 7b, 8x7b, 32-billion, 0.5b. MoE names use active-ish sum as conservative upper bound.
+    total = 0.0
+    found = False
+    for multiplier, value in re.findall(r"(?:(\d+)\s*x\s*)?(\d+(?:\.\d+)?)\s*(?:b|bn|billion)\b", lowered):
+        count = float(value) * (int(multiplier) if multiplier else 1)
+        total += count
+        found = True
+    if found:
+        return total
+    # Common size shorthand in model IDs: 12B-it often appears as 12b-it after lower().
+    match = re.search(r"(?<!\d)(\d+(?:\.\d+)?)[-_ ]?b(?:[-_./ ]|$)", lowered)
+    return float(match.group(1)) if match else None
+
+
+def _float_or_none(value: Any) -> float | None:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _join_url(base_url: str, path: str) -> str:
+    return base_url.rstrip("/") + "/" + path.lstrip("/")
+
+
+model_catalog = ModelCatalog()

arena/model_provider.py

@@ -0,0 +1,168 @@
+"""Chat model provider factory for Swarm sessions."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from langchain.chat_models import init_chat_model
+
+from .model_catalog import (
+    DEFAULT_GEMINI_BASE_URL,
+    DEFAULT_HF_ROUTER_BASE_URL,
+    DEFAULT_LOCAL_MODEL,
+    DEFAULT_NEBIUS_BASE_URL,
+    DEFAULT_OPENROUTER_BASE_URL,
+    ModelProviderConfig,
+)
+
+
+DEFAULT_MODEL = "openai/o4-mini"
+
+
+def normalize_openrouter_model(model: str) -> str:
+    normalized = model.strip()
+    for prefix in ("openrouter:", "openrouter/"):
+        if normalized.startswith(prefix):
+            return normalized.removeprefix(prefix)
+    return normalized
+
+
+def create_chat_model(config: ModelProviderConfig | None = None) -> Any:
+    is_env_config = config is None
+    config = config or _config_from_env()
+    provider = config.provider
+    if not is_env_config and _hosted_provider(provider) and not config.key_value():
+        raise ValueError(_missing_key_message(provider))
+    if provider == "openrouter":
+        return _openrouter_model(config)
+    if provider == "gemini":
+        return _gemini_model(config)
+    if provider == "local" and not config.base_url.strip():
+        return _cached_local_model(config)
+    if provider in {"custom", "openai-compatible", "local", "nebius", "huggingface", "hf"}:
+        return _openai_compatible_model(config)
+    raise ValueError(f"Unsupported model provider: {provider}")
+
+
+def _config_from_env() -> ModelProviderConfig:
+    provider = os.getenv("DEEPAGENT_MODEL_PROVIDER", "openrouter")
+    return ModelProviderConfig(
+        provider=provider,
+        model=os.getenv("DEEPAGENT_MODEL", DEFAULT_MODEL),
+        api_key=_env_key_for_provider(provider),
+        base_url=os.getenv("DEEPAGENT_MODEL_BASE_URL", ""),
+    )
+
+
+def _openrouter_model(config: ModelProviderConfig) -> Any:
+    model = config.model.strip() or DEFAULT_MODEL
+    model = normalize_openrouter_model(model)
+    api_key = config.key_value()
+    kwargs: dict[str, Any] = {"temperature": 0.2, "max_tokens": 4096}
+    if api_key:
+        kwargs["api_key"] = api_key
+    if config.base_url and config.base_url != DEFAULT_OPENROUTER_BASE_URL:
+        kwargs["base_url"] = config.base_url
+    return init_chat_model(f"openrouter:{model}", **kwargs)
+
+
+def _openai_compatible_model(config: ModelProviderConfig) -> Any:
+    provider = config.provider
+    model = config.model.strip() or DEFAULT_MODEL
+    base_url = config.base_url.strip() or _default_base_url(provider)
+    api_key = config.key_value()
+    from langchain_openai import ChatOpenAI
+
+    return ChatOpenAI(
+        model=model,
+        api_key=api_key or _placeholder_api_key(provider),
+        base_url=base_url,
+        temperature=0.2,
+        max_tokens=4096,
+    )
+
+
+def _cached_local_model(config: ModelProviderConfig) -> Any:
+    from .local_model import CachedLocalChatModel
+
+    return CachedLocalChatModel(
+        model_id=config.model.strip() or DEFAULT_LOCAL_MODEL,
+        temperature=0.2,
+        max_new_tokens=int(os.getenv("LOCAL_MODEL_MAX_NEW_TOKENS", "2048")),
+        cache_ttl_seconds=int(os.getenv("LOCAL_MODEL_CACHE_TTL_SECONDS", str(30 * 60))),
+    )
+
+
+def _gemini_model(config: ModelProviderConfig) -> Any:
+    try:
+        from langchain_google_genai import ChatGoogleGenerativeAI
+    except ImportError as exc:
+        raise RuntimeError(
+            "Gemini provider requires langchain-google-genai. Install dependencies from requirements.txt."
+        ) from exc
+    model = config.model.strip() or os.getenv("GEMINI_MODEL", "gemini-2.5-flash")
+    api_key = config.key_value()
+    kwargs: dict[str, Any] = {"model": model, "temperature": 0.2, "max_output_tokens": 4096}
+    if api_key:
+        kwargs["api_key"] = api_key
+    if config.base_url and config.base_url != DEFAULT_GEMINI_BASE_URL:
+        kwargs["client_options"] = {"api_endpoint": config.base_url}
+    return ChatGoogleGenerativeAI(**kwargs)
+
+
+def _default_base_url(provider: str) -> str:
+    if provider == "openrouter":
+        return DEFAULT_OPENROUTER_BASE_URL
+    if provider == "nebius":
+        return DEFAULT_NEBIUS_BASE_URL
+    if provider in {"huggingface", "hf"}:
+        return DEFAULT_HF_ROUTER_BASE_URL
+    if provider == "local":
+        return os.getenv("LOCAL_MODEL_BASE_URL", "http://127.0.0.1:8000/v1")
+    return ""
+
+
+def _placeholder_api_key(provider: str) -> str:
+    if provider in {"local", "custom", "openai-compatible"}:
+        return "not-needed"
+    return ""
+
+
+def _hosted_provider(provider: str) -> bool:
+    return provider in {"openrouter", "gemini", "nebius", "huggingface", "hf"}
+
+
+def _missing_key_message(provider: str) -> str:
+    if provider == "openrouter":
+        return "OPENROUTER_API_KEY must be set"
+    if provider == "gemini":
+        return "GEMINI_API_KEY must be set"
+    if provider == "nebius":
+        return "NEBIUS_API_KEY must be set"
+    if provider in {"huggingface", "hf"}:
+        return "HF_TOKEN or HUGGINGFACE_API_KEY must be set"
+    return "Model provider API key must be set"
+
+
+def _env_key_for_provider(provider: str) -> str:
+    provider = provider.lower().replace("_", "-")
+    if provider == "openrouter":
+        return os.getenv("OPENROUTER_API_KEY", "")
+    if provider == "nebius":
+        return os.getenv("NEBIUS_API_KEY", "")
+    if provider in {"huggingface", "hf"}:
+        return os.getenv("HF_TOKEN", "") or os.getenv("HUGGINGFACE_API_KEY", "")
+    if provider == "gemini":
+        return os.getenv("GEMINI_API_KEY", "") or os.getenv("GOOGLE_API_KEY", "")
+    if provider == "local":
+        return os.getenv("LOCAL_MODEL_API_KEY", "")
+    return os.getenv("CUSTOM_MODEL_API_KEY", "")
+
+
+def default_model_for_provider(provider: str) -> str:
+    if provider == "local":
+        return os.getenv("LOCAL_MODEL_ID", DEFAULT_LOCAL_MODEL)
+    if provider == "gemini":
+        return os.getenv("GEMINI_MODEL", "gemini-2.5-flash")
+    return os.getenv("DEEPAGENT_MODEL", DEFAULT_MODEL)

arena/models.py

@@ -0,0 +1,152 @@
+"""Domain records for the agent swarm workbench."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from .model_catalog import ModelProviderConfig, ModelProviderSelection
+
+
+RunStatus = Literal["queued", "planning", "working", "validating", "completed", "failed", "interrupted"]
+TaskStatus = Literal["planned", "active", "blocked", "completed", "failed", "interrupted"]
+ValidationCheckSource = Literal["generated", "user", "stagehand"]
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class Criteria(BaseModel):
+    text: str = Field(min_length=1)
+
+
+class ValidationCheck(BaseModel):
+    id: str = Field(min_length=1)
+    name: str = Field(min_length=1)
+    command: str = Field(min_length=1)
+    source: ValidationCheckSource = "generated"
+
+
+class RunRequest(BaseModel):
+    prompt: str = Field(min_length=1)
+    criteria: list[Criteria] = Field(default_factory=list)
+    user_tests: list[str] = Field(default_factory=list)
+    model_provider: ModelProviderConfig | None = None
+
+    @field_validator("user_tests")
+    @classmethod
+    def require_non_empty_user_tests(cls, value: list[str]) -> list[str]:
+        if any(not test.strip() for test in value):
+            raise ValueError("user tests must be non-empty")
+        return value
+
+
+class RunTask(BaseModel):
+    id: str = Field(min_length=1)
+    title: str = Field(min_length=1)
+    status: TaskStatus = "planned"
+
+
+class RunEvent(BaseModel):
+    id: str = Field(min_length=1)
+    message: str = Field(min_length=1)
+    created_at: datetime = Field(default_factory=utc_now)
+
+
+class RunArtifact(BaseModel):
+    id: str = Field(min_length=1)
+    name: str = Field(min_length=1)
+    archive_pointer: str = Field(min_length=1)
+    created_at: datetime = Field(default_factory=utc_now)
+
+
+class ValidationCheckResult(BaseModel):
+    check_id: str = Field(min_length=1)
+    passed: bool
+    output: str = ""
+
+
+class ValidationReport(BaseModel):
+    run_id: str = Field(min_length=1)
+    passed: bool
+    results: list[ValidationCheckResult] = Field(default_factory=list)
+    summary: str = ""
+    risks: list[str] = Field(default_factory=list)
+    rubric_score: float | None = None
+    rubric_feedback: str = ""
+    created_at: datetime = Field(default_factory=utc_now)
+
+
+class CodebaseArchive(BaseModel):
+    pointer: str = Field(min_length=1)
+    file_count: int = Field(ge=0)
+    size_bytes: int = Field(ge=0)
+
+
+class RunView(BaseModel):
+    id: str
+    prompt: str
+    status: RunStatus
+    criteria: list[Criteria]
+    user_tests: list[str]
+    tasks: list[RunTask]
+    events: list[RunEvent]
+    artifacts: list[RunArtifact]
+    validation_checks: list[ValidationCheck]
+    validation_report: ValidationReport | None = None
+    codebase_archive: CodebaseArchive | None = None
+    model_provider: ModelProviderSelection | None = None
+    summary: str = ""
+    created_at: datetime
+    updated_at: datetime
+
+
+class Run(BaseModel):
+    id: str = Field(min_length=1)
+    prompt: str = Field(min_length=1)
+    rejoin_token: str = Field(min_length=24)
+    status: RunStatus = "queued"
+    criteria: list[Criteria] = Field(default_factory=list)
+    user_tests: list[str] = Field(default_factory=list)
+    tasks: list[RunTask] = Field(default_factory=list)
+    events: list[RunEvent] = Field(default_factory=list)
+    artifacts: list[RunArtifact] = Field(default_factory=list)
+    validation_checks: list[ValidationCheck] = Field(default_factory=list)
+    validation_report: ValidationReport | None = None
+    codebase_archive: CodebaseArchive | None = None
+    model_provider: ModelProviderSelection | None = None
+    summary: str = ""
+    created_at: datetime = Field(default_factory=utc_now)
+    updated_at: datetime = Field(default_factory=utc_now)
+
+    @model_validator(mode="after")
+    def validate_completion_has_report(self) -> "Run":
+        if self.status == "completed" and self.validation_report is None:
+            raise ValueError("completed run requires validation report")
+        if self.status == "completed" and self.codebase_archive is None:
+            raise ValueError("completed run requires codebase archive")
+        if self.validation_report is not None and self.validation_report.run_id != self.id:
+            raise ValueError("validation report run id must match run id")
+        return self
+
+    def to_view(self) -> RunView:
+        return RunView(
+            id=self.id,
+            prompt=self.prompt,
+            status=self.status,
+            criteria=self.criteria,
+            user_tests=self.user_tests,
+            tasks=self.tasks,
+            events=sorted(self.events, key=lambda event: event.created_at),
+            artifacts=self.artifacts,
+            validation_checks=self.validation_checks,
+            validation_report=self.validation_report,
+            codebase_archive=self.codebase_archive,
+            model_provider=self.model_provider,
+            summary=self.summary,
+            created_at=self.created_at,
+            updated_at=self.updated_at,
+        )

arena/paths.py

@@ -0,0 +1,10 @@
+"""Shared filesystem paths for the Arena package."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+PACKAGE_ROOT = Path(__file__).resolve().parent
+REPO_ROOT = PACKAGE_ROOT.parent
+SKILLS_ROOT = REPO_ROOT / "skills"

arena/redis_client.py

@@ -0,0 +1,57 @@
+"""Redis client primitives shared by Run and Codebase storage seams.
+
+These primitives are domain-neutral so the prompt-first stores can depend on
+them without dragging legacy Match code along. ``arena.match_store`` re-exports
+these names for backward compatibility while legacy modules are still in tree.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Protocol
+from urllib import request
+from urllib.error import HTTPError, URLError
+
+
+class RedisStoreError(ValueError):
+    pass
+
+
+class RedisClient(Protocol):
+    def execute(self, *args: str):
+        ...
+
+
+@dataclass
+class UpstashRedisRestClient:
+    url: str
+    token: str
+    timeout_seconds: int = 10
+
+    def execute(self, *args: str):
+        payload = json.dumps(list(args)).encode("utf-8")
+        req = request.Request(
+            self.url.rstrip("/"),
+            data=payload,
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {self.token}",
+                "Content-Type": "application/json",
+            },
+        )
+        try:
+            with request.urlopen(req, timeout=self.timeout_seconds) as response:
+                body = response.read().decode("utf-8")
+        except HTTPError as exc:
+            raise RedisStoreError(f"upstash redis command failed: HTTP {exc.code}") from exc
+        except URLError as exc:
+            raise RedisStoreError("upstash redis command failed") from exc
+
+        try:
+            data = json.loads(body)
+        except json.JSONDecodeError as exc:
+            raise RedisStoreError("upstash redis returned invalid json") from exc
+        if "error" in data:
+            raise RedisStoreError(str(data["error"]))
+        return data.get("result")

arena/run_flow.py

@@ -0,0 +1,177 @@
+"""Prompt-first Run lifecycle conductor."""
+
+from __future__ import annotations
+
+import queue
+import threading
+from dataclasses import dataclass
+from typing import Any
+
+from .codebase_archive import CodebaseArchiveStore, archive_to_zip_bytes
+from .event_bus import EventBus
+from .run_models import (
+    Run,
+    RunRequest,
+    RunView,
+)
+from .validation_models import (
+    ValidationReport,
+)
+from .run_journal import InvalidRunStatusTransition, RunJournal
+from .run_store import RunAccessView, RunStore
+from .service_payloads import ZipPayload
+from .swarm_runtime import SwarmRuntime
+from .validator_graph import ValidatorGraph
+from .validator_plan import ValidatorPlan
+
+
+class RunFlowError(ValueError):
+    pass
+
+
+class RunArchiveNotFound(RunFlowError):
+    pass
+
+
+@dataclass
+class RunFlow:
+    run_store: RunStore
+    swarm_runtime: SwarmRuntime
+    validator_graph: ValidatorGraph
+    archive_store: CodebaseArchiveStore
+    event_bus: EventBus | None = None
+    journal: RunJournal | None = None
+
+    def __post_init__(self) -> None:
+        if self.event_bus is None:
+            self.event_bus = EventBus()
+        if self.journal is None:
+            self.journal = RunJournal(run_store=self.run_store, event_bus=self.event_bus)
+
+    def create_run(self, request: RunRequest) -> RunAccessView:
+        access = self._create_and_seed_run(request)
+        self.journal.transition(access.run.id, "working")
+        self._execute_swarm_and_validate(access.run.id, request.user_tests)
+        return RunAccessView(token=access.token, run=self.journal.get_run(access.run.id))
+
+    def start_run(self, request: RunRequest) -> RunAccessView:
+        access = self._create_and_seed_run(request)
+        self.journal.transition(access.run.id, "planning")
+        self.journal.publish(access.run.id, {"kind": "run_started", "run_id": access.run.id})
+        threading.Thread(
+            target=self._execute_background,
+            args=(access.run.id, request.user_tests),
+            name=f"run-{access.run.id}",
+            daemon=True,
+        ).start()
+        return access
+
+    def rejoin(self, token: str) -> RunAccessView:
+        return self.journal.rejoin(token)
+
+    def get_run(self, run_id: str) -> RunView:
+        return self.journal.get_run(run_id)
+
+    def cancel_run(self, run_id: str) -> RunView:
+        self.swarm_runtime.close_run(run_id)
+        return self.journal.cancel_run(run_id)
+
+    def add_run_message(self, run_id: str, message: str) -> RunView:
+        self.swarm_runtime.touch_run(run_id)
+        return self.journal.record_user_message(run_id, message)
+
+    def subscribe_events(self, run_id: str) -> queue.Queue[dict[str, Any] | None]:
+        return self.journal.subscribe_events(run_id)
+
+    def get_codebase_zip(self, run_id: str) -> ZipPayload:
+        run = self.journal.get_run(run_id)
+        if run.codebase_archive is None:
+            raise RunArchiveNotFound("run has no codebase archive")
+        archive = self.archive_store.load(run.codebase_archive.pointer)
+        return ZipPayload(
+            filename=f"{run.id}.zip",
+            data=archive_to_zip_bytes(archive),
+        )
+
+    def validate_run(self, run_id: str) -> ValidationReport:
+        run = self.journal.get_run(run_id)
+        if run.validation_report is not None:
+            if run.status != "completed":
+                self.journal.transition(run.id, "completed")
+            return run.validation_report
+        if run.codebase_archive is None:
+            raise RunArchiveNotFound("run has no codebase archive")
+        context = self.journal.build_validator_context(run.id)
+        return self._validate_completed_run(
+            run.id,
+            plan=ValidatorPlan.from_checks(run.validation_checks, context=context),
+        )
+
+    def _execute_background(self, run_id: str, user_tests: list[str]) -> None:
+        try:
+            self.journal.transition(run_id, "working")
+            self._execute_swarm_and_validate(run_id, user_tests)
+            if not self.journal.is_interrupted(run_id):
+                self.journal.publish(run_id, {"kind": "swarm_complete", "run_id": run_id})
+        except Exception as exc:
+            import traceback
+            tb = traceback.format_exc()
+            msg = f"{exc}\n{tb[-1000:]}"
+            print(f"[RUN FAILED {run_id}] {msg}", flush=True)
+            self.swarm_runtime.close_run(run_id)
+            if not self.journal.is_interrupted(run_id):
+                self.journal.transition(run_id, "failed")
+            self.journal.publish(run_id, {"kind": "error", "run_id": run_id, "message": str(exc)})
+            self.journal.close_stream(run_id)
+
+    def _create_and_seed_run(self, request: RunRequest) -> RunAccessView:
+        access = self.journal.create_run(request)
+        try:
+            self.swarm_runtime.start_run(_run_from_access(access), model_provider=request.model_provider)
+        except TypeError:
+            self.swarm_runtime.start_run(_run_from_access(access))
+        return access
+
+    def _execute_swarm_and_validate(self, run_id: str, user_tests: list[str]) -> ValidationReport:
+        result = self.swarm_runtime.execute_run(run_id, user_tests=user_tests)
+        if self.journal.is_interrupted(run_id):
+            self.journal.close_stream(run_id)
+            return ValidationReport(
+                run_id=run_id,
+                passed=False,
+                summary="Run interrupted before validation.",
+                risks=["Run was cancelled before validation completed."],
+            )
+        self.journal.save_swarm_result(run_id, result)
+        context = self.journal.build_validator_context(run_id)
+        plan = ValidatorPlan.from_user_tests(user_tests, context=context)
+        self.journal.save_validation_checks(run_id, plan.checks)
+        return self._validate_completed_run(run_id, plan=plan)
+
+    def _validate_completed_run(self, run_id: str, *, plan: ValidatorPlan | None = None) -> ValidationReport:
+        run = self.journal.get_run(run_id)
+        if run.codebase_archive is None:
+            raise RunArchiveNotFound("run has no codebase archive")
+        if plan is None:
+            context = self.journal.build_validator_context(run.id)
+            plan = ValidatorPlan.from_checks(run.validation_checks, context=context)
+        self.journal.begin_validation(run.id)
+        report = self.validator_graph.validate(
+            run_id=run.id,
+            codebase_archive=run.codebase_archive,
+            plan=plan,
+        )
+        self.journal.complete_validation(run.id, report)
+        return report
+
+
+def _run_from_access(access: RunAccessView) -> Run:
+    return Run(
+        id=access.run.id,
+        prompt=access.run.prompt,
+        criteria=access.run.criteria,
+        user_tests=access.run.user_tests,
+        model_provider=access.run.model_provider,
+        rejoin_token=access.token,
+        status=access.run.status,
+    )

arena/run_journal.py

@@ -0,0 +1,148 @@
+"""Run journal module for status, event, task, and stream persistence."""
+
+from __future__ import annotations
+
+import queue
+from dataclasses import dataclass
+from typing import Any
+from uuid import uuid4
+
+from .event_bus import EventBus
+from .run_models import (
+    CodebaseArchive,
+    RunEvent,
+    RunRequest,
+    RunStatus,
+    RunTask,
+    RunView,
+)
+from .run_store import RunAccessView, RunStore
+from .validation_models import ValidationCheck, ValidationReport
+from .validator_plan import ValidatorContext
+
+
+class RunJournalError(ValueError):
+    pass
+
+
+class InvalidRunStatusTransition(RunJournalError):
+    pass
+
+
+TERMINAL_STATUSES: frozenset[RunStatus] = frozenset({"completed", "failed", "interrupted"})
+
+STATUS_TRANSITIONS: dict[RunStatus, frozenset[RunStatus]] = {
+    "queued": frozenset({"planning", "working", "validating", "interrupted", "failed"}),
+    "planning": frozenset({"working", "validating", "completed", "interrupted", "failed"}),
+    "working": frozenset({"validating", "completed", "interrupted", "failed"}),
+    "validating": frozenset({"completed", "interrupted", "failed"}),
+    "completed": frozenset({"interrupted"}),
+    "failed": frozenset({"interrupted"}),
+    "interrupted": frozenset(),
+}
+
+
+@dataclass
+class RunJournal:
+    """Owns persisted Run mutation and stream publication rules."""
+
+    run_store: RunStore
+    event_bus: EventBus
+
+    def create_run(self, request: RunRequest) -> RunAccessView:
+        access = self.run_store.create_run(request)
+        self.event_bus.add_listener(access.run.id, self._persist_runtime_event)
+        return access
+
+    def rejoin(self, token: str) -> RunAccessView:
+        return self.run_store.rejoin(token)
+
+    def get_run(self, run_id: str) -> RunView:
+        return self.run_store.get_run_view(run_id)
+
+    def subscribe_events(self, run_id: str) -> queue.Queue[dict[str, Any] | None]:
+        return self.event_bus.subscribe(run_id)
+
+    def publish(self, run_id: str, event: dict[str, Any]) -> None:
+        self.event_bus.publish(run_id, event)
+
+    def close_stream(self, run_id: str) -> None:
+        self.event_bus.close(run_id)
+
+    def transition(self, run_id: str, target: RunStatus) -> RunView:
+        current = self.get_run(run_id).status
+        allowed = STATUS_TRANSITIONS.get(current, frozenset())
+        if target not in allowed:
+            raise InvalidRunStatusTransition(
+                f"cannot transition run {run_id} from {current!r} to {target!r}"
+            )
+        return self.run_store.save_status(run_id, target)
+
+    def is_interrupted(self, run_id: str) -> bool:
+        return self.get_run(run_id).status == "interrupted"
+
+    def cancel_run(self, run_id: str) -> RunView:
+        view = self.get_run(run_id)
+        if view.status in TERMINAL_STATUSES:
+            return view
+        try:
+            self.run_store.mark_active_tasks_interrupted(run_id)
+        except Exception:
+            pass
+        self.transition(run_id, "interrupted")
+        self.close_stream(run_id)
+        return self.get_run(run_id)
+
+    def record_user_message(self, run_id: str, message: str) -> RunView:
+        event = RunEvent(id=f"event_{uuid4().hex}", message=f"User: {message.strip()}")
+        view = self.run_store.append_event(run_id, event)
+        self.publish(run_id, {"kind": "event", "event": event.model_dump(mode="json")})
+        return view
+
+    def save_swarm_result(self, run_id: str, result: Any) -> None:
+        self.run_store.save_tasks(run_id, result.tasks)
+        for event in result.events:
+            self.run_store.append_event(run_id, event)
+        self.run_store.save_codebase_archive(run_id, result.codebase_archive)
+        self.run_store.save_summary(run_id, result.summary)
+
+    def save_codebase_archive(self, run_id: str, archive: CodebaseArchive) -> RunView:
+        return self.run_store.save_codebase_archive(run_id, archive)
+
+    def save_validation_checks(self, run_id: str, checks: list[ValidationCheck]) -> RunView:
+        return self.run_store.save_validation_checks(run_id, checks)
+
+    def save_validation_report(self, run_id: str, report: ValidationReport) -> RunView:
+        return self.run_store.save_validation_report(run_id, report)
+
+    def build_validator_context(self, run_id: str) -> ValidatorContext:
+        run = self.get_run(run_id)
+        return ValidatorContext(prompt=run.prompt, criteria=tuple(run.criteria))
+
+    def begin_validation(self, run_id: str) -> None:
+        self.transition(run_id, "validating")
+        self.publish(run_id, {"kind": "validating", "run_id": run_id, "status": "validating"})
+
+    def complete_validation(self, run_id: str, report: ValidationReport) -> None:
+        self.save_validation_report(run_id, report)
+        self.transition(run_id, "completed")
+        self.publish(run_id, {"kind": "validated", "run_id": run_id, "status": "completed"})
+        self.close_stream(run_id)
+
+    def _persist_runtime_event(self, run_id: str, event: dict[str, Any]) -> None:
+        try:
+            kind = event.get("kind")
+            if kind in {"task_created", "task_updated"}:
+                task = RunTask.model_validate(event.get("task"))
+                self._upsert_task(run_id, task)
+            elif kind == "event":
+                run_event = RunEvent.model_validate(event.get("event"))
+                self.run_store.append_event(run_id, run_event)
+        except Exception:
+            pass
+
+    def _upsert_task(self, run_id: str, task: RunTask) -> None:
+        current = self.get_run(run_id).tasks
+        tasks = [item for item in current if item.id != task.id]
+        tasks.append(task)
+        self.run_store.save_tasks(run_id, tasks)

arena/run_models.py

@@ -0,0 +1,34 @@
+"""Prompt-first Run domain model import surface.
+
+New Run/Swarm modules should import from here instead of the shared model file.
+"""
+
+from __future__ import annotations
+
+from .models import (
+    CodebaseArchive,
+    ModelProviderConfig,
+    ModelProviderSelection,
+    Run,
+    RunArtifact,
+    RunEvent,
+    RunRequest,
+    RunStatus,
+    RunTask,
+    RunView,
+    TaskStatus,
+)
+
+__all__ = [
+    "CodebaseArchive",
+    "ModelProviderConfig",
+    "ModelProviderSelection",
+    "Run",
+    "RunArtifact",
+    "RunEvent",
+    "RunRequest",
+    "RunStatus",
+    "RunTask",
+    "RunView",
+    "TaskStatus",
+]

arena/run_store.py

@@ -0,0 +1,313 @@
+"""Run store seam for prompt-first agent swarm work."""
+
+from __future__ import annotations
+
+import os
+import secrets
+from typing import Protocol
+from uuid import uuid4
+
+from pydantic import BaseModel
+
+from .models import utc_now
+from .redis_client import RedisClient, UpstashRedisRestClient
+from .run_models import (
+    CodebaseArchive,
+    Run,
+    RunEvent,
+    RunRequest,
+    RunStatus,
+    RunTask,
+    RunView,
+)
+from .validation_models import (
+    ValidationCheck,
+    ValidationReport,
+)
+
+
+class RunStoreError(ValueError):
+    pass
+
+
+class RunNotFound(RunStoreError):
+    pass
+
+
+class InvalidRunToken(RunStoreError):
+    pass
+
+
+class RunAccessView(BaseModel):
+    token: str
+    run: RunView
+
+
+class RunStore(Protocol):
+    def create_run(self, request: RunRequest) -> RunAccessView:
+        ...
+
+    def rejoin(self, token: str) -> RunAccessView:
+        ...
+
+    def get_run_view(self, run_id: str) -> RunView:
+        ...
+
+    def save_tasks(self, run_id: str, tasks: list[RunTask]) -> RunView:
+        ...
+
+    def save_status(self, run_id: str, status: RunStatus) -> RunView:
+        ...
+
+    def save_summary(self, run_id: str, summary: str) -> RunView:
+        ...
+
+    def append_event(self, run_id: str, event: RunEvent) -> RunView:
+        ...
+
+    def save_codebase_archive(self, run_id: str, archive: CodebaseArchive) -> RunView:
+        ...
+
+    def save_validation_checks(self, run_id: str, checks: list[ValidationCheck]) -> RunView:
+        ...
+
+    def save_validation_report(self, run_id: str, report: ValidationReport) -> RunView:
+        ...
+
+    def mark_active_tasks_interrupted(self, run_id: str) -> RunView:
+        ...
+
+
+class BaseRunStore:
+    def _new_id(self, prefix: str) -> str:
+        return f"{prefix}_{uuid4().hex}"
+
+    def _new_token(self) -> str:
+        return secrets.token_urlsafe(32)
+
+    def _touch(self, run: Run) -> None:
+        run.updated_at = utc_now()
+
+    def _append_event_once(self, run: Run, event: RunEvent) -> None:
+        if not any(existing.id == event.id for existing in run.events):
+            run.events.append(event)
+
+
+class InMemoryRunStore(BaseRunStore):
+    def __init__(self) -> None:
+        self._runs_by_id: dict[str, Run] = {}
+        self._run_tokens: dict[str, str] = {}
+
+    def create_run(self, request: RunRequest) -> RunAccessView:
+        token = self._new_token()
+        run = Run(
+            id=self._new_id("run"),
+            prompt=request.prompt,
+            criteria=request.criteria,
+            user_tests=request.user_tests,
+            rejoin_token=token,
+            model_provider=request.model_provider.public_selection() if request.model_provider else None,
+        )
+        self._runs_by_id[run.id] = run
+        self._run_tokens[token] = run.id
+        return RunAccessView(token=token, run=run.to_view())
+
+    def rejoin(self, token: str) -> RunAccessView:
+        run_id = self._run_tokens.get(token)
+        if run_id is None:
+            raise InvalidRunToken("token does not match any run")
+        return RunAccessView(token=token, run=self.get_run_view(run_id))
+
+    def get_run_view(self, run_id: str) -> RunView:
+        return self._get(run_id).to_view()
+
+    def save_tasks(self, run_id: str, tasks: list[RunTask]) -> RunView:
+        run = self._get(run_id)
+        run.tasks = tasks
+        self._touch(run)
+        return run.to_view()
+
+    def save_status(self, run_id: str, status: RunStatus) -> RunView:
+        run = self._get(run_id)
+        run.status = status
+        self._touch(run)
+        return run.to_view()
+
+    def save_summary(self, run_id: str, summary: str) -> RunView:
+        run = self._get(run_id)
+        run.summary = summary
+        self._touch(run)
+        return run.to_view()
+
+    def append_event(self, run_id: str, event: RunEvent) -> RunView:
+        run = self._get(run_id)
+        self._append_event_once(run, event)
+        self._touch(run)
+        return run.to_view()
+
+    def save_codebase_archive(self, run_id: str, archive: CodebaseArchive) -> RunView:
+        run = self._get(run_id)
+        run.codebase_archive = archive
+        self._touch(run)
+        return run.to_view()
+
+    def save_validation_checks(self, run_id: str, checks: list[ValidationCheck]) -> RunView:
+        run = self._get(run_id)
+        run.validation_checks = checks
+        self._touch(run)
+        return run.to_view()
+
+    def save_validation_report(self, run_id: str, report: ValidationReport) -> RunView:
+        run = self._get(run_id)
+        if report.run_id != run.id:
+            raise ValueError("validation report run id must match run id")
+        run.validation_report = report
+        self._touch(run)
+        return run.to_view()
+
+    def mark_active_tasks_interrupted(self, run_id: str) -> RunView:
+        run = self._get(run_id)
+        run.tasks = [
+            task.model_copy(update={"status": "interrupted"}) if task.status == "active" else task
+            for task in run.tasks
+        ]
+        self._touch(run)
+        return run.to_view()
+
+    def _get(self, run_id: str) -> Run:
+        run = self._runs_by_id.get(run_id)
+        if run is None:
+            raise RunNotFound("run not found")
+        return run
+
+
+class RedisRunStore(BaseRunStore):
+    """Redis-backed RunStore using Upstash REST-compatible commands."""
+
+    def __init__(self, *, client: RedisClient, key_prefix: str = "arena") -> None:
+        self._client = client
+        self._key_prefix = key_prefix.rstrip(":")
+
+    def create_run(self, request: RunRequest) -> RunAccessView:
+        token = self._new_token()
+        run = Run(
+            id=self._new_id("run"),
+            prompt=request.prompt,
+            criteria=request.criteria,
+            user_tests=request.user_tests,
+            rejoin_token=token,
+            model_provider=request.model_provider.public_selection() if request.model_provider else None,
+        )
+        self._save_run(run)
+        self._set(self._token_key(token), run.id)
+        return RunAccessView(token=token, run=run.to_view())
+
+    def rejoin(self, token: str) -> RunAccessView:
+        run_id = self._get_value(self._token_key(token))
+        if run_id is None:
+            raise InvalidRunToken("token does not match any run")
+        return RunAccessView(token=token, run=self.get_run_view(run_id))
+
+    def get_run_view(self, run_id: str) -> RunView:
+        return self._get(run_id).to_view()
+
+    def save_tasks(self, run_id: str, tasks: list[RunTask]) -> RunView:
+        run = self._get(run_id)
+        run.tasks = tasks
+        self._touch(run)
+        self._save_run(run)
+        return run.to_view()
+
+    def save_status(self, run_id: str, status: RunStatus) -> RunView:
+        run = self._get(run_id)
+        run.status = status
+        self._touch(run)
+        self._save_run(run)
+        return run.to_view()
+
+    def save_summary(self, run_id: str, summary: str) -> RunView:
+        run = self._get(run_id)
+        run.summary = summary
+        self._touch(run)
+        self._save_run(run)
+        return run.to_view()
+
+    def append_event(self, run_id: str, event: RunEvent) -> RunView:
+        run = self._get(run_id)
+        self._append_event_once(run, event)
+        self._touch(run)
+        self._save_run(run)
+        return run.to_view()
+
+    def save_codebase_archive(self, run_id: str, archive: CodebaseArchive) -> RunView:
+        run = self._get(run_id)
+        run.codebase_archive = archive
+        self._touch(run)
+        self._save_run(run)
+        return run.to_view()
+
+    def save_validation_checks(self, run_id: str, checks: list[ValidationCheck]) -> RunView:
+        run = self._get(run_id)
+        run.validation_checks = checks
+        self._touch(run)
+        self._save_run(run)
+        return run.to_view()
+
+    def save_validation_report(self, run_id: str, report: ValidationReport) -> RunView:
+        run = self._get(run_id)
+        if report.run_id != run.id:
+            raise ValueError("validation report run id must match run id")
+        run.validation_report = report
+        self._touch(run)
+        self._save_run(run)
+        return run.to_view()
+
+    def mark_active_tasks_interrupted(self, run_id: str) -> RunView:
+        run = self._get(run_id)
+        run.tasks = [
+            task.model_copy(update={"status": "interrupted"}) if task.status == "active" else task
+            for task in run.tasks
+        ]
+        self._touch(run)
+        self._save_run(run)
+        return run.to_view()
+
+    def _get(self, run_id: str) -> Run:
+        payload = self._get_value(self._run_key(run_id))
+        if payload is None:
+            raise RunNotFound("run not found")
+        return Run.model_validate_json(payload)
+
+    def _save_run(self, run: Run) -> None:
+        self._set(self._run_key(run.id), run.model_dump_json())
+
+    def _get_value(self, key: str) -> str | None:
+        value = self._client.execute("GET", key)
+        if value is None:
+            return None
+        return str(value)
+
+    def _set(self, key: str, value: str) -> None:
+        self._client.execute("SET", key, value)
+
+    def _run_key(self, run_id: str) -> str:
+        return f"{self._key_prefix}:run:{run_id}"
+
+    def _token_key(self, token: str) -> str:
+        return f"{self._key_prefix}:run-token:{token}"
+
+
+def create_run_store() -> RunStore:
+    provider = os.getenv("RUN_STORE_PROVIDER", "memory").lower()
+    if provider == "memory":
+        return InMemoryRunStore()
+    if provider == "redis":
+        url = os.getenv("UPSTASH_REDIS_REST_URL", "")
+        token = os.getenv("UPSTASH_REDIS_REST_TOKEN", "")
+        if not url or not token:
+            raise ValueError(
+                "UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN are required "
+                "when RUN_STORE_PROVIDER=redis"
+            )
+        return RedisRunStore(client=UpstashRedisRestClient(url=url, token=token))
+    raise ValueError(f"unsupported run store provider: {provider}")

arena/sandbox_lease.py

@@ -0,0 +1,92 @@
+"""Idle leases for costly sandbox resources."""
+
+from __future__ import annotations
+
+import os
+import threading
+from dataclasses import dataclass
+from typing import Callable
+
+
+DEFAULT_SANDBOX_TTL_SECONDS = 30 * 60
+
+
+CloseSandbox = Callable[[], None]
+ExpireSandbox = Callable[[], None]
+
+
+@dataclass
+class SandboxLease:
+    lease_id: str
+    close: CloseSandbox
+    on_expire: ExpireSandbox | None = None
+    timer: threading.Timer | None = None
+
+
+class SandboxLeaseManager:
+    """Owns idle TTL, touch, and close behaviour for sandbox resources."""
+
+    def __init__(self, *, ttl_seconds: float | None = None) -> None:
+        self.ttl_seconds = ttl_seconds if ttl_seconds is not None else sandbox_ttl_seconds_from_env()
+        self._leases: dict[str, SandboxLease] = {}
+        self._lock = threading.RLock()
+
+    def start(
+        self,
+        lease_id: str,
+        close: CloseSandbox,
+        *,
+        on_expire: ExpireSandbox | None = None,
+    ) -> None:
+        self.close(lease_id)
+        lease = SandboxLease(lease_id=lease_id, close=close, on_expire=on_expire)
+        with self._lock:
+            self._leases[lease_id] = lease
+            lease.timer = self._schedule(lease_id)
+
+    def touch(self, lease_id: str) -> bool:
+        with self._lock:
+            lease = self._leases.get(lease_id)
+            if lease is None:
+                return False
+            if lease.timer is not None:
+                lease.timer.cancel()
+            lease.timer = self._schedule(lease_id)
+            return True
+
+    def close(self, lease_id: str) -> bool:
+        with self._lock:
+            lease = self._leases.pop(lease_id, None)
+        if lease is None:
+            return False
+        if lease.timer is not None:
+            lease.timer.cancel()
+        lease.close()
+        return True
+
+    def _expire(self, lease_id: str) -> None:
+        with self._lock:
+            lease = self._leases.pop(lease_id, None)
+        if lease is None:
+            return
+        lease.close()
+        if lease.on_expire is not None:
+            lease.on_expire()
+
+    def _schedule(self, lease_id: str) -> threading.Timer | None:
+        if self.ttl_seconds <= 0:
+            return None
+        timer = threading.Timer(self.ttl_seconds, self._expire, args=(lease_id,))
+        timer.daemon = True
+        timer.start()
+        return timer
+
+
+def sandbox_ttl_seconds_from_env() -> float:
+    raw = os.getenv("DEEPAGENT_SANDBOX_TTL_SECONDS", "").strip()
+    if not raw:
+        return float(DEFAULT_SANDBOX_TTL_SECONDS)
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        return float(DEFAULT_SANDBOX_TTL_SECONDS)

arena/service.py

@@ -0,0 +1,348 @@
+"""Run workbench interface for HTTP, Gradio, and tests."""
+
+from __future__ import annotations
+
+import os
+import json
+from typing import Callable
+
+import dotenv
+
+from .agent import AgentSession, create_session
+from .codebase_archive import CodebaseArchiveStore, create_codebase_archive_store
+from .event_bus import EventBus
+from .model_catalog import ModelProviderConfig, ProviderModel, model_catalog, model_id_is_eligible, model_id_parameter_count_b
+from .run_models import RunRequest, RunView
+from .validation_models import ValidationReport
+from .run_flow import RunArchiveNotFound, RunFlow
+from .run_store import RunAccessView, RunStore, create_run_store
+from .service_payloads import TextPayload, ZipPayload
+from .skill_catalog import SkillInfo, discover_skills
+from .swarm_runtime import SwarmRuntime
+from .thread_inspector import FileAccessFailed
+from .validator_executor import create_validator_executor
+from .validator_graph import ValidatorGraph, OpenRouterRubricReviewer
+
+
+class ArenaServiceError(Exception):
+    pass
+
+
+def _maybe_llm_rubric_reviewer():
+    dotenv.load_dotenv()
+    if os.environ.get("OPENROUTER_API_KEY"):
+        return OpenRouterRubricReviewer()
+    return None
+
+
+SessionFactory = Callable[..., AgentSession]
+
+
+class ArenaService:
+    """Stable API boundary for the prompt-first Run workbench.
+
+    The Thread inspection surface lives in ``ThreadInspector``; debug routes and
+    tests should depend on ``ThreadInspector`` directly instead of reaching
+    into this class.
+    """
+
+    def __init__(
+        self,
+        *,
+        session_factory: SessionFactory = create_session,
+        run_store: RunStore | None = None,
+        swarm_runtime: SwarmRuntime | None = None,
+        archive_store: CodebaseArchiveStore | None = None,
+        validator_graph: ValidatorGraph | None = None,
+        run_flow: RunFlow | None = None,
+    ) -> None:
+        self._session_factory = session_factory
+        self._archive_store = archive_store or create_codebase_archive_store()
+        self._run_store = run_store or create_run_store()
+        event_bus = EventBus()
+        self._event_bus = event_bus
+        self._swarm_runtime = swarm_runtime or SwarmRuntime(
+            session_factory=self._attempt_session,
+            archive_store=self._archive_store,
+            event_bus=event_bus,
+        )
+        rubric = _maybe_llm_rubric_reviewer()
+        self._validator_graph = validator_graph or ValidatorGraph(
+            executor=create_validator_executor(self._archive_store),
+            rubric_reviewer=rubric,
+        )
+        self._run_flow = run_flow or RunFlow(
+            run_store=self._run_store,
+            swarm_runtime=self._swarm_runtime,
+            validator_graph=self._validator_graph,
+            archive_store=self._archive_store,
+            event_bus=event_bus,
+        )
+
+    def health(self) -> dict[str, str]:
+        return {"status": "ok"}
+
+    def list_skills(self) -> list[SkillInfo]:
+        return discover_skills()
+
+    def list_provider_models(self, config: ModelProviderConfig | None = None) -> list[ProviderModel]:
+        return model_catalog.list_models(config)
+
+    def refresh_provider_models(self, config: ModelProviderConfig | None = None) -> list[ProviderModel]:
+        return model_catalog.refresh_models(config)
+
+    def create_run(self, request: RunRequest) -> RunAccessView:
+        self._validate_model_provider(request.model_provider)
+        return self._run_flow.create_run(request)
+
+    def start_run(self, request: RunRequest) -> RunAccessView:
+        self._validate_model_provider(request.model_provider)
+        return self._run_flow.start_run(request)
+
+    def cancel_run(self, run_id: str) -> RunView:
+        return self._run_flow.cancel_run(run_id)
+
+    def add_run_message(self, run_id: str, message: str) -> RunView:
+        return self._run_flow.add_run_message(run_id, message)
+
+    def subscribe_events(self, run_id: str):
+        return self._run_flow.subscribe_events(run_id)
+
+    def rejoin_run(self, token: str) -> RunAccessView:
+        return self._run_flow.rejoin(token)
+
+    def get_run(self, run_id: str) -> RunView:
+        return self._run_flow.get_run(run_id)
+
+    def get_run_codebase_zip(self, run_id: str) -> ZipPayload:
+        try:
+            return self._run_flow.get_codebase_zip(run_id)
+        except RunArchiveNotFound as exc:
+            raise FileAccessFailed("run has no codebase archive") from exc
+
+    def get_run_field_notes(self, run_id: str) -> TextPayload:
+        run = self.get_run(run_id)
+        return TextPayload(
+            filename=f"{run.id}-field-notes.md",
+            content_type="text/markdown; charset=utf-8",
+            data=_field_notes_markdown(run),
+        )
+
+    def get_run_trace_json(self, run_id: str) -> TextPayload:
+        run = self.get_run(run_id)
+        return TextPayload(
+            filename=f"{run.id}-trace.json",
+            content_type="application/json; charset=utf-8",
+            data=json.dumps(run.model_dump(mode="json"), indent=2, ensure_ascii=False),
+        )
+
+    def get_run_submission_markdown(self, run_id: str) -> TextPayload:
+        run = self.get_run(run_id)
+        return TextPayload(
+            filename=f"{run.id}-submission.md",
+            content_type="text/markdown; charset=utf-8",
+            data=_submission_markdown(run),
+        )
+
+    def get_run_space_readme(self, run_id: str) -> TextPayload:
+        run = self.get_run(run_id)
+        return TextPayload(
+            filename=f"{run.id}-space-README.md",
+            content_type="text/markdown; charset=utf-8",
+            data=_space_readme_markdown(run),
+        )
+
+    def validate_run(self, run_id: str) -> ValidationReport:
+        try:
+            return self._run_flow.validate_run(run_id)
+        except RunArchiveNotFound as exc:
+            raise FileAccessFailed("run has no codebase archive") from exc
+
+    def _attempt_session(self, thread_id: str | None, model_provider: ModelProviderConfig | None = None) -> AgentSession:
+        try:
+            return self._session_factory(thread_id, model_provider)
+        except TypeError:
+            try:
+                return self._session_factory(thread_id)
+            except TypeError:
+                return self._session_factory()
+
+    def _validate_model_provider(self, config: ModelProviderConfig | None) -> None:
+        if config is None:
+            return
+        model = config.model.strip()
+        if not model:
+            raise ArenaServiceError("Choose a fetched model before starting the Run")
+        if not model_id_is_eligible(model):
+            count = model_id_parameter_count_b(model)
+            if count is None:
+                raise ArenaServiceError("Model size is unknown; choose a fetched model with <=32B parameters")
+            raise ArenaServiceError(f"Model has {count:g}B parameters; requirement is <=32B")
+
+
+def _field_notes_markdown(run: RunView) -> str:
+    events = "\n".join(
+        f"- {event.created_at.isoformat()}: {event.message}"
+        for event in run.events
+    ) or "- No events recorded."
+    tasks = "\n".join(f"- {task.title}: {task.status}" for task in run.tasks) or "- No tasks recorded."
+    checks = "\n".join(
+        f"- {check.name}: `{check.command}` ({check.source})"
+        for check in run.validation_checks
+    ) or "- No validation checks recorded."
+    provider = "server default"
+    if run.model_provider is not None:
+        provider = f"{run.model_provider.provider} / {run.model_provider.model or 'provider default'}"
+    return f"""# Field Notes: Backyard Demo Builder Run
+
+## Real Person
+
+- Tester: Mom
+- Role: Real-estate agent
+- Problem: follow up with buyer/renter leads without committing to expensive app development first.
+
+## Demo Hypothesis
+
+If a tiny Gradio demo can show lead reminders and message drafts quickly, the real-estate agent can decide whether to scrap or scale the workflow before paying for full software.
+
+## Run
+
+- Run ID: `{run.id}`
+- Status: `{run.status}`
+- Model provider: {provider}
+- Prompt: {run.prompt}
+
+## Tasks
+
+{tasks}
+
+## Events
+
+{events}
+
+## Validation Checks
+
+{checks}
+
+## Mom Test Questions
+
+- Would you use this with real leads?
+- Which reminder is most useful?
+- Which follow-up message would you send as-is?
+- What is missing before this becomes a real app?
+- Scrap or scale?
+
+## Quote Placeholder
+
+> Add one direct quote after the real test.
+"""
+
+
+def _submission_markdown(run: RunView) -> str:
+    provider = "server default"
+    model_requirement = "Choose one fetched model with a known size <=32B before the final public run."
+    if run.model_provider is not None:
+        provider = f"{run.model_provider.provider} / {run.model_provider.model or 'provider default'}"
+        if run.model_provider.model:
+            size = model_id_parameter_count_b(run.model_provider.model)
+            if size is not None:
+                model_requirement = f"{run.model_provider.model} parsed as {size:g}B parameters, within <=32B."
+
+    archive = "No demo package yet."
+    if run.codebase_archive is not None:
+        archive = f"{run.codebase_archive.file_count} files, {run.codebase_archive.size_bytes} bytes."
+
+    report = "Not validated yet."
+    if run.validation_report is not None:
+        report = "Passed" if run.validation_report.passed else "Failed"
+
+    return f"""# Backyard Demo Builder Submission Pack
+
+## Hackathon
+
+- Track: Build Small Hackathon Chapter 1 - Backyard AI
+- Real person: Mom, real-estate agent
+- Problem: Cheaply test a lead follow-up reminder demo before paying to build a full CRM.
+- Run ID: `{run.id}`
+- Run status: `{run.status}`
+
+## Small Model Requirement
+
+- Provider/model: {provider}
+- Proof: {model_requirement}
+
+## Built Demo
+
+- Prompt: {run.prompt}
+- Package: {archive}
+- Validation: {report}
+- Download package: `/runs/{run.id}/codebase.zip`
+- Field notes: `/runs/{run.id}/field_notes.md`
+- Trace: `/runs/{run.id}/trace.json`
+
+## Demo Video Script
+
+1. Show the real problem: lead follow-up gets messy and expensive software is risky.
+2. Start Backyard Demo Builder with the real-estate follow-up template.
+3. Build the tiny Gradio CRM demo.
+4. Open the generated demo and add sample leads.
+5. Show next-action reminders and follow-up message drafts.
+6. Record Mom Test feedback: useful reminder, message quality, scrap-or-scale decision.
+7. Close with what would be scaled after approval.
+
+## Social Post Draft
+
+Built Backyard Demo Builder for Chapter 1 Backyard AI. It turns one real workflow from my mom, a real-estate agent, into a tiny Gradio demo package so she can test lead reminders before we spend time building a full app. Small model, real user, fast scrap-or-scale loop.
+
+## Bonus Checklist
+
+- Off the Grid: Works as a small local Gradio demo package.
+- Well-Tuned: Template narrows the SLM prompt to one real workflow.
+- Sharing is Caring: Submission pack includes reusable script and README.
+- Field Notes: `/runs/{run.id}/field_notes.md`
+- Llama Champion: Eligible if the selected fetched model is a Llama-family <=32B model.
+
+## Final Checklist
+
+- Space runs on port 7860.
+- README explains the real person and problem.
+- Demo video shows the generated app, not only this builder.
+- Field notes include one direct quote from Mom.
+- No raw API key stored in Run data, Redis, logs, trace, or archive.
+"""
+
+
+def _space_readme_markdown(run: RunView) -> str:
+    title = "Backyard Demo Builder"
+    return f"""---
+title: {title}
+emoji: W
+colorFrom: gray
+colorTo: zinc
+sdk: gradio
+sdk_version: 6.0.0
+app_file: app.py
+pinned: false
+---
+
+# {title}
+
+Chapter 1 Backyard AI demo builder for quick scrap-or-scale product tests.
+
+This Space builds tiny Gradio demo packages from one real-person workflow. The default template is a real-estate follow-up reminder demo for Mom, a real-estate agent.
+
+## Run
+
+```bash
+python app.py
+```
+
+Hugging Face Spaces serves Gradio on port `7860`.
+
+## Current Evidence
+
+- Source run: `{run.id}`
+- Status: `{run.status}`
+- Field notes: `/runs/{run.id}/field_notes.md`
+- Submission pack: `/runs/{run.id}/submission.md`
+"""

arena/service_payloads.py

@@ -0,0 +1,17 @@
+"""Shared service payload models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class ZipPayload(BaseModel):
+    filename: str
+    content_type: str = "application/zip"
+    data: bytes
+
+
+class TextPayload(BaseModel):
+    filename: str
+    content_type: str = "text/plain; charset=utf-8"
+    data: str

arena/skill_catalog.py

@@ -0,0 +1,54 @@
+"""Discovery for repository-bundled DeepAgents skills."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from .paths import SKILLS_ROOT
+
+
+class SkillInfo(BaseModel):
+    name: str
+    description: str
+    path: str
+    virtual_path: str
+
+
+def discover_skills(root: Path = SKILLS_ROOT) -> list[SkillInfo]:
+    """Return skills mounted into DeepAgents at /skills/."""
+    if not root.exists():
+        return []
+
+    skills = []
+    for skill_file in sorted(root.glob("*/SKILL.md")):
+        metadata = _frontmatter(skill_file)
+        name = metadata.get("name") or skill_file.parent.name
+        skills.append(
+            SkillInfo(
+                name=name,
+                description=metadata.get("description", ""),
+                path=str(skill_file.relative_to(root.parent)),
+                virtual_path=f"/skills/{skill_file.parent.name}/SKILL.md",
+            )
+        )
+    return skills
+
+
+def _frontmatter(path: Path) -> dict[str, str]:
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---\n"):
+        return {}
+
+    end = text.find("\n---", 4)
+    if end == -1:
+        return {}
+
+    metadata: dict[str, str] = {}
+    for line in text[4:end].splitlines():
+        if ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        metadata[key.strip()] = value.strip().strip("\"'")
+    return metadata

arena/smoke.py

@@ -0,0 +1,73 @@
+"""Small smoke entrypoints for project task targets."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import tempfile
+from pathlib import Path
+
+from deepagents.backends import LocalShellBackend
+
+from .agent import create_session
+from .codebase_archive import LocalCodebaseArchiveStore
+from .codebase_handoff import CodebaseHandoff
+from .models import CodebaseArchive, ValidationCheck
+from .validator_executor import create_validator_executor
+from .validator_graph import ValidatorGraph
+from .validator_plan import ValidatorPlan
+
+
+def smoke_agent() -> None:
+    os.environ.setdefault("OPENROUTER_API_KEY", "sk-or-test")
+    os.environ.setdefault("DEEPAGENT_SANDBOX_PROVIDER", "local")
+    session = create_session("smoke")
+    try:
+        print(session.thread_id, session.provider, type(session.backend).__name__)
+    finally:
+        session.close()
+
+
+def smoke_validator() -> None:
+    with tempfile.TemporaryDirectory(prefix="agent-swarm-validator-smoke-") as tmp:
+        root = Path(tmp)
+        sandbox_root = root / "sandbox"
+        backend = LocalShellBackend(root_dir=sandbox_root, virtual_mode=True, inherit_env=False)
+        backend.write("/workspace/answer.txt", "ok")
+        snapshot_root = root / "archives"
+        archive_store = LocalCodebaseArchiveStore(root_dir=snapshot_root)
+        handoff = CodebaseHandoff(archive_store=archive_store, root_dir=snapshot_root)
+        pointer = handoff.snapshot_backend_workspace(backend, "smoke-run")
+        executor = create_validator_executor(archive_store=archive_store)
+        executor.root_dir = snapshot_root
+        try:
+            report = ValidatorGraph(executor=executor).validate(
+                run_id="smoke-run",
+                codebase_archive=CodebaseArchive(pointer=pointer, file_count=1, size_bytes=2),
+                plan=ValidatorPlan.from_checks([
+                    ValidationCheck(
+                        id="check-1",
+                        name="file",
+                        command="test -f answer.txt",
+                        source="generated",
+                    ),
+                ]),
+            )
+        finally:
+            executor.close()
+        print(json.dumps(report.model_dump(mode="json"), sort_keys=True, default=str))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("target", choices=["agent", "validator"])
+    args = parser.parse_args()
+    if args.target == "agent":
+        smoke_agent()
+    elif args.target == "validator":
+        smoke_validator()
+
+
+if __name__ == "__main__":
+    main()

arena/stagehand_validator.py

@@ -0,0 +1,180 @@
+"""Stagehand visual validation — opens built web apps in remote Browserbase browsers."""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Any
+
+from playwright.sync_api import sync_playwright
+from stagehand import Stagehand
+
+
+class StagehandValidationError(Exception):
+    pass
+
+
+def run_stagehand_check(
+    url: str,
+    instruction: str,
+    timeout_seconds: int = 30,
+) -> tuple[bool, str]:
+    """Open a URL in a Browserbase remote browser and validate behavior.
+
+    Uses Stagehand to navigate to a running web app and perform natural-language
+    validation (click, observe, extract).
+
+    Args:
+        url: The URL of the running web app to validate.
+        instruction: Natural-language instruction describing what to verify.
+        timeout_seconds: Maximum time to wait for the check.
+
+    Returns:
+        A tuple of (passed: bool, output: str) with the check result.
+    """
+    browserbase_api_key = os.environ.get("BROWSERBASE_API_KEY", "")
+    model_api_key = os.environ.get("MODEL_API_KEY", os.environ.get("OPENROUTER_API_KEY", ""))
+
+    if not browserbase_api_key:
+        return False, "BROWSERBASE_API_KEY is not configured"
+
+    if not model_api_key:
+        return False, "MODEL_API_KEY or OPENROUTER_API_KEY is not configured"
+
+    try:
+        with Stagehand(
+            server="remote",
+            browserbase_api_key=browserbase_api_key,
+            model_api_key=model_api_key,
+        ) as client:
+            session = client.sessions.start(
+                model_name="openrouter/anthropic/claude-sonnet-4-6",
+                browser={"type": "browserbase"},
+            )
+
+            cdp_url = session.data.cdp_url
+            if not cdp_url:
+                client.sessions.end(session.id)
+                return False, "No CDP URL returned from Browserbase session"
+
+            output_parts: list[str] = []
+            try:
+                with sync_playwright() as p:
+                    browser_conn = p.chromium.connect_over_cdp(cdp_url)
+                    context = browser_conn.contexts[0] if browser_conn.contexts else browser_conn.new_context()
+                    page = context.pages[0] if context.pages else context.new_page()
+
+                    client.sessions.navigate(session.id, url=url)
+                    page.wait_for_load_state("domcontentloaded")
+                    time.sleep(2)
+
+                    observe_stream = client.sessions.observe(
+                        session.id,
+                        instruction=instruction,
+                        stream_response=True,
+                        x_stream_response="true",
+                    )
+                    for event in observe_stream:
+                        data = _event_data(event)
+                        if data:
+                            output_parts.append(data)
+
+                    passed = "error" not in " ".join(output_parts).lower()
+                    return passed, "\n".join(output_parts) or "Observed page successfully."
+
+            finally:
+                browser_conn.close() if "browser_conn" in dir() else None
+
+            client.sessions.end(session.id)
+
+    except Exception as exc:
+        return False, f"Stagehand validation error: {exc}"
+
+
+def run_stagehand_static_check(
+    url: str,
+    checks: list[str],
+) -> tuple[bool, str]:
+    """Run multiple Stagehand checks against a single page session.
+
+    Opens one Browserbase session and runs each check instruction sequentially.
+    More efficient than opening a new session per check.
+
+    Args:
+        url: The URL to validate.
+        checks: List of natural-language instructions to verify.
+
+    Returns:
+        A tuple of (passed: bool, output: str).
+    """
+    browserbase_api_key = os.environ.get("BROWSERBASE_API_KEY", "")
+    model_api_key = os.environ.get("MODEL_API_KEY", os.environ.get("OPENROUTER_API_KEY", ""))
+
+    if not browserbase_api_key:
+        return False, "BROWSERBASE_API_KEY is not configured"
+    if not model_api_key:
+        return False, "MODEL_API_KEY or OPENROUTER_API_KEY is not configured"
+    if not checks:
+        return True, "No checks to run"
+
+    try:
+        with Stagehand(
+            server="remote",
+            browserbase_api_key=browserbase_api_key,
+            model_api_key=model_api_key,
+        ) as client:
+            session = client.sessions.start(
+                model_name="openrouter/anthropic/claude-sonnet-4-6",
+                browser={"type": "browserbase"},
+            )
+
+            cdp_url = session.data.cdp_url
+            if not cdp_url:
+                client.sessions.end(session.id)
+                return False, "No CDP URL from Browserbase"
+
+            all_outputs: list[str] = []
+            try:
+                with sync_playwright() as p:
+                    browser_conn = p.chromium.connect_over_cdp(cdp_url)
+                    context = browser_conn.contexts[0] if browser_conn.contexts else browser_conn.new_context()
+                    page = context.pages[0] if context.pages else context.new_page()
+
+                    client.sessions.navigate(session.id, url=url)
+                    page.wait_for_load_state("domcontentloaded")
+                    time.sleep(2)
+
+                    for i, check in enumerate(checks):
+                        observe_stream = client.sessions.observe(
+                            session.id,
+                            instruction=check,
+                            stream_response=True,
+                            x_stream_response="true",
+                        )
+                        for event in observe_stream:
+                            data = _event_data(event)
+                            if data:
+                                all_outputs.append(f"[Check {i+1}] {data}")
+
+                    output_text = "\n".join(all_outputs) if all_outputs else "All checks observed."
+                    passed = "error" not in output_text.lower()
+                    return passed, output_text
+
+            finally:
+                browser_conn.close() if "browser_conn" in dir() else None
+
+            client.sessions.end(session.id)
+
+    except Exception as exc:
+        return False, f"Stagehand validation error: {exc}"
+
+
+def _event_data(event: Any) -> str | None:
+    if hasattr(event, "data") and event.data:
+        data = event.data
+        if hasattr(data, "message"):
+            return str(data.message)
+        if isinstance(data, dict):
+            return str(data.get("message", str(data)))
+        return str(data)
+    return None

arena/swarm_runtime.py

@@ -0,0 +1,95 @@
+"""Prompt-first DeepAgent Swarm runtime."""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, Callable
+
+from .agent import AgentSession, create_session
+from .codebase_archive import CodebaseArchiveStore, create_codebase_archive_store
+from .event_bus import EventBus
+from .codebase_handoff import CodebaseHandoff
+from .model_catalog import ModelProviderConfig
+from .run_models import Run
+from .sandbox_lease import SandboxLeaseManager
+from .swarm_session import SwarmRunResult, SwarmRunSession, SwarmRunState
+
+SessionFactory = Callable[..., AgentSession]
+
+
+class SwarmRuntime:
+    """Starts and drives one DeepAgent Swarm for a prompt-first Run."""
+
+    def __init__(
+        self,
+        session_factory: SessionFactory = create_session,
+        archive_store: CodebaseArchiveStore | None = None,
+        event_bus: EventBus | None = None,
+        sandbox_ttl_seconds: float | None = None,
+        sandbox_leases: SandboxLeaseManager | None = None,
+    ) -> None:
+        self._session_factory = session_factory
+        self._archive_store = archive_store or create_codebase_archive_store()
+        self._codebase_handoff = CodebaseHandoff(archive_store=self._archive_store)
+        self._event_bus = event_bus or EventBus()
+        self._runs: dict[str, SwarmRunSession] = {}
+        self._lock = threading.RLock()
+        self._sandbox_leases = sandbox_leases or SandboxLeaseManager(ttl_seconds=sandbox_ttl_seconds)
+
+    def start_run(self, run: Run, *, model_provider: ModelProviderConfig | None = None) -> SwarmRunState:
+        session = self._create_session(run.id, model_provider)
+        run_session = SwarmRunSession(
+            run=run,
+            session=session,
+            codebase_handoff=self._codebase_handoff,
+            archive_store=self._archive_store,
+            emit=lambda kind, data, run_id=run.id: self._emit(run_id, kind, data),
+        )
+        with self._lock:
+            self._runs[run.id] = run_session
+        self._sandbox_leases.start(
+            run.id,
+            run_session.state.session.close,
+            on_expire=lambda run_id=run.id: self._forget_run(run_id),
+        )
+        return run_session.state
+
+    def execute_run(self, run_id: str, *, user_tests: list[str] | None = None, max_retries: int = 3) -> SwarmRunResult:
+        try:
+            return self._require_run(run_id).execute(user_tests=user_tests, max_retries=max_retries)
+        finally:
+            self.close_run(run_id)
+
+    def close_run(self, run_id: str) -> None:
+        with self._lock:
+            state = self._runs.pop(run_id, None)
+        if state is None:
+            return
+        self._sandbox_leases.close(run_id)
+
+    def touch_run(self, run_id: str) -> bool:
+        with self._lock:
+            state = self._runs.get(run_id)
+            if state is None:
+                return False
+        return self._sandbox_leases.touch(run_id)
+
+    def _emit(self, run_id: str, kind: str, data: dict[str, Any]) -> None:
+        self._event_bus.publish(run_id, {"kind": kind, **data})
+
+    def _create_session(self, run_id: str, model_provider: ModelProviderConfig | None) -> AgentSession:
+        try:
+            return self._session_factory(run_id, model_provider)
+        except TypeError:
+            return self._session_factory(run_id)
+
+    def _require_run(self, run_id: str) -> SwarmRunSession:
+        with self._lock:
+            run_session = self._runs.get(run_id)
+        if run_session is None:
+            raise KeyError(f"unknown run: {run_id}")
+        return run_session
+
+    def _forget_run(self, run_id: str) -> None:
+        with self._lock:
+            self._runs.pop(run_id, None)

arena/swarm_session.py

@@ -0,0 +1,284 @@
+"""One live Swarm session for a prompt-first Run."""
+
+from __future__ import annotations
+
+import functools
+import os
+import re
+import shlex
+from dataclasses import dataclass
+from typing import Any, Callable
+from uuid import uuid4
+
+from .agent import AgentSession
+from .codebase_archive import CodebaseArchiveStore
+from .codebase_handoff import CodebaseHandoff
+from .run_models import CodebaseArchive, Run, RunEvent, RunTask
+
+
+CONTEXT_DIR = "/context"
+DEFAULT_WORKSPACE_DIR = "/workspace"
+
+RunEventEmitter = Callable[[str, dict[str, Any]], None]
+
+
+@dataclass
+class SwarmRunState:
+    run_id: str
+    thread_id: str
+    session: AgentSession
+
+
+@dataclass(frozen=True)
+class SwarmRunResult:
+    summary: str
+    tasks: list[RunTask]
+    events: list[RunEvent]
+    codebase_archive: CodebaseArchive
+
+
+class SwarmRunSession:
+    """Drives the live AgentSession and snapshots its Workspace."""
+
+    def __init__(
+        self,
+        *,
+        run: Run,
+        session: AgentSession,
+        codebase_handoff: CodebaseHandoff,
+        archive_store: CodebaseArchiveStore,
+        emit: RunEventEmitter,
+    ) -> None:
+        normalize_backend_paths(session.backend, session.workspace_dir)
+        self.state = SwarmRunState(run_id=run.id, thread_id=session.thread_id, session=session)
+        self._codebase_handoff = codebase_handoff
+        self._archive_store = archive_store
+        self._emit = emit
+        self._seed_context(run)
+
+    def execute(self, *, user_tests: list[str] | None = None, max_retries: int = 3) -> SwarmRunResult:
+        run_id = self.state.run_id
+        task = RunTask(id=f"task_{uuid4().hex}", title="Build codebase", status="active")
+        start_event = RunEvent(id=f"event_{uuid4().hex}", message="Coordinator started work")
+        self._emit("task_created", {"task": task.model_dump()})
+        self._emit("event", {"event": start_event.model_dump(mode="json")})
+
+        workspace_dir = self.state.session.workspace_dir
+        events: list[RunEvent] = [start_event]
+        user_tests = user_tests or []
+        self.state.session.messages.append(
+            {
+                "role": "user",
+                "content": (
+                    "Read /context/run.md, plan the work, delegate to subagents when useful, "
+                    f"build the demo package in {workspace_dir}, run relevant checks, and summarize changed files. "
+                    "For Backyard Demo Builder runs, produce a Space-ready Gradio demo plus README.md, "
+                    "handoff_spec.md, and field_notes.md unless the Run context says otherwise."
+                ),
+            }
+        )
+        self._emit("status", {"status": "working"})
+
+        self._invoke_agent()
+        summary = self._run_tests_and_retry(workspace_dir, user_tests, max_retries)
+
+        archive_pointer = self._codebase_handoff.snapshot_backend_workspace(
+            self.state.session.backend,
+            run_id,
+            workspace_dir=workspace_dir,
+        )
+        archive = self._archive_store.load(archive_pointer)
+        completed_task = task.model_copy(update={"status": "completed"})
+        completed_event = RunEvent(id=f"event_{uuid4().hex}", message=summary or "Coordinator finished work")
+        self._emit("task_updated", {"task": completed_task.model_dump()})
+        self._emit("event", {"event": completed_event.model_dump(mode="json")})
+        self._emit(
+            "archive",
+            {
+                "pointer": archive_pointer,
+                "file_count": len(archive.files),
+                "size_bytes": sum(file.size_bytes for file in archive.files),
+            },
+        )
+        self._emit("status", {"status": "validating"})
+        events.append(completed_event)
+        return SwarmRunResult(
+            summary=summary,
+            tasks=[completed_task],
+            events=events,
+            codebase_archive=CodebaseArchive(
+                pointer=archive_pointer,
+                file_count=len(archive.files),
+                size_bytes=sum(file.size_bytes for file in archive.files),
+            ),
+        )
+
+    def _run_tests_and_retry(self, workspace_dir: str, user_tests: list[str], max_retries: int) -> str:
+        for attempt in range(1, max_retries + 1):
+            failed_tests = self._run_user_tests(workspace_dir, user_tests)
+            if not failed_tests:
+                return self._invoke_agent() or "Build complete."
+
+            if attempt < max_retries:
+                self.state.session.messages.append(
+                    {
+                        "role": "user",
+                        "content": (
+                            f"Fix attempt {attempt}/{max_retries}. The following user tests failed:\n\n"
+                            + "\n".join(f"  {test}\n    {output}" for test, output in failed_tests)
+                            + "\n\nFix the issues and re-run the tests."
+                        ),
+                    }
+                )
+                self._emit(
+                    "event",
+                    {
+                        "event": RunEvent(
+                            id=f"event_{uuid4().hex}",
+                            message=f"Fix attempt {attempt}/{max_retries}: {len(failed_tests)} test(s) failed",
+                        ).model_dump(mode="json"),
+                    },
+                )
+                self._invoke_agent()
+
+        return self._invoke_agent() or "Build finished after retries."
+
+    def _run_user_tests(self, workspace_dir: str, user_tests: list[str]) -> list[tuple[str, str]]:
+        execute = getattr(self.state.session.backend, "execute", None)
+        if not user_tests or not callable(execute):
+            return []
+        failed: list[tuple[str, str]] = []
+        for test in user_tests:
+            try:
+                result = execute(f"cd {shlex.quote(workspace_dir)} && {test}")
+                exit_code = getattr(result, "exit_code", None)
+                output = getattr(result, "output", "") or ""
+                if exit_code is not None and exit_code != 0:
+                    failed.append((test, output[:500]))
+            except Exception:
+                pass
+        return failed
+
+    def _invoke_agent(self) -> str:
+        result = self.state.session.agent.invoke(
+            {"messages": self.state.session.messages},
+            config={"configurable": {"thread_id": self.state.thread_id, "run_id": self.state.run_id}},
+        )
+        content = last_message_text(result)
+        if content:
+            self.state.session.messages.append({"role": "assistant", "content": content})
+        return content
+
+    def _seed_context(self, run: Run) -> None:
+        self._write_file(f"{CONTEXT_DIR}/run.md", run_markdown(run, self.state.session.workspace_dir))
+        self._ensure_workspace(self.state.session.workspace_dir)
+
+    def _ensure_workspace(self, workspace_dir: str) -> None:
+        execute = getattr(self.state.session.backend, "execute", None)
+        if callable(execute):
+            result = execute(f"mkdir -p {workspace_dir}")
+            if getattr(result, "exit_code", 0) == 0:
+                return
+        self._write_file(f"{workspace_dir}/.keep", "")
+
+    def _write_file(self, path: str, content: str) -> None:
+        result = self.state.session.backend.write(path, content)
+        if getattr(result, "error", None):
+            raise RuntimeError(f"could not write sandbox file: {path}")
+
+
+def normalize_backend_paths(backend: Any, workspace_dir: str) -> None:
+    """Wrap backend writes to redirect host-looking paths into the virtual Workspace."""
+    original_write = backend.write
+    original_edit = getattr(backend, "edit_file", None)
+
+    bad_prefixes: list[str] = []
+    home = os.path.expanduser("~")
+    if home and workspace_dir:
+        bad_prefixes.append(os.path.join(home, workspace_dir.lstrip("/")))
+
+    @functools.wraps(original_write)
+    def safe_write(path: str, content: str, *args: Any, **kwargs: Any) -> Any:
+        path = _normalize_path_prefix(path, bad_prefixes, workspace_dir)
+        path = normalize_host_path_to_virtual(path, workspace_dir)
+        return original_write(path, content, *args, **kwargs)
+
+    backend.write = safe_write
+
+    if original_edit is not None:
+
+        @functools.wraps(original_edit)
+        def safe_edit(path: str, *args: Any, **kwargs: Any) -> Any:
+            path = _normalize_path_prefix(path, bad_prefixes, workspace_dir)
+            path = normalize_host_path_to_virtual(path, workspace_dir)
+            return original_edit(path, *args, **kwargs)
+
+        backend.edit_file = safe_edit
+
+
+def _normalize_path_prefix(path: str, bad_prefixes: list[str], workspace_dir: str) -> str:
+    for bad_prefix in bad_prefixes:
+        if path.startswith(bad_prefix):
+            return workspace_dir + path[len(bad_prefix):]
+    return path
+
+
+def normalize_host_path_to_virtual(path: str, virtual_workspace: str) -> str:
+    if not path.startswith("/") or virtual_workspace.startswith(path):
+        return path
+    workspace_pattern = re.escape(virtual_workspace.rstrip("/")) + r"(?=/|$)"
+    match = re.search(workspace_pattern, path)
+    if match is None:
+        return path
+    return path[match.start():]
+
+
+def run_markdown(run: Run, workspace_dir: str = DEFAULT_WORKSPACE_DIR) -> str:
+    criteria = "\n".join(f"- {item.text}" for item in run.criteria) or "- None"
+    user_tests = "\n".join(f"- `{test}`" for test in run.user_tests) or "- None"
+    model_provider = "- None"
+    if run.model_provider is not None:
+        model_provider = (
+            f"- Provider: {run.model_provider.provider}\n"
+            f"- Model: {run.model_provider.model or 'provider default'}\n"
+            f"- Endpoint: {run.model_provider.base_url or 'provider default'}"
+        )
+    return (
+        f"# Run {run.id}\n\n"
+        "## User Prompt\n\n"
+        f"{run.prompt}\n\n"
+        "## Model Provider\n\n"
+        f"{model_provider}\n\n"
+        "## Criteria\n\n"
+        f"{criteria}\n\n"
+        "## User Tests\n\n"
+        f"{user_tests}\n\n"
+        "## Workspace\n\n"
+        f"Build the demo package in `{workspace_dir}`.\n\n"
+        "## Required Demo Package Files\n\n"
+        "- `app.py`: runnable Gradio demo app\n"
+        "- `README.md`: setup and demo purpose\n"
+        "- `handoff_spec.md`: what to build if the real person approves\n"
+        "- `field_notes.md`: real-person test plan, feedback questions, demo script notes\n"
+    )
+
+
+def content_text(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        return "\n".join(
+            str(item.get("text", item)) if isinstance(item, dict) else str(item) for item in value
+        )
+    return str(value or "")
+
+
+def last_message_text(result: dict[str, Any]) -> str:
+    messages = result.get("messages", [])
+    if not messages:
+        return ""
+    last = messages[-1]
+    content = getattr(last, "content", None)
+    if content is None and isinstance(last, dict):
+        content = last.get("content")
+    return content_text(content)

arena/thread_inspector.py

@@ -0,0 +1,137 @@
+"""Manual Thread inspection for ad-hoc AgentSession debugging."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from pydantic import BaseModel
+
+from .agent import AgentSession, create_session
+
+
+class ThreadInspectorError(Exception):
+    pass
+
+
+class ThreadNotFound(ThreadInspectorError):
+    pass
+
+
+class AgentRunFailed(ThreadInspectorError):
+    pass
+
+
+class FileAccessFailed(ThreadInspectorError):
+    pass
+
+
+class ThreadResponse(BaseModel):
+    thread_id: str
+    sandbox_provider: str
+
+
+class MessageResponse(BaseModel):
+    thread_id: str
+    content: str
+
+
+class FileEntry(BaseModel):
+    path: str
+    type: str
+
+
+SessionFactory = Callable[..., AgentSession]
+
+
+class ThreadInspector:
+    """Owns the ad-hoc AgentSession interface used by debug routes."""
+
+    def __init__(self, *, session_factory: SessionFactory = create_session) -> None:
+        self._session_factory = session_factory
+        self._sessions: dict[str, AgentSession] = {}
+
+    @property
+    def sessions(self) -> dict[str, AgentSession]:
+        return self._sessions
+
+    def create_thread(self) -> ThreadResponse:
+        session = self._session_factory()
+        self._sessions[session.thread_id] = session
+        return ThreadResponse(thread_id=session.thread_id, sandbox_provider=session.provider)
+
+    def send_message(self, thread_id: str, content: str) -> MessageResponse:
+        session = self._session(thread_id)
+        session.messages.append({"role": "user", "content": content})
+        try:
+            result = session.agent.invoke(
+                {"messages": session.messages},
+                config={"configurable": {"thread_id": thread_id}},
+            )
+        except Exception as exc:
+            raise AgentRunFailed("agent run failed") from exc
+
+        response = _last_message_text(result)
+        session.messages.append({"role": "assistant", "content": response})
+        return MessageResponse(thread_id=thread_id, content=response)
+
+    def list_files(self, thread_id: str, path: str = "/") -> list[FileEntry]:
+        session = self._session(thread_id)
+        result = session.backend.ls(path)
+        if getattr(result, "error", None):
+            raise FileAccessFailed("could not list files")
+        entries = getattr(result, "entries", [])
+        return [_file_entry(entry) for entry in entries]
+
+    def read_file(self, thread_id: str, path: str) -> dict[str, str]:
+        session = self._session(thread_id)
+        result = session.backend.read(path)
+        if getattr(result, "error", None):
+            raise FileAccessFailed("could not read file")
+        file_data = getattr(result, "file_data", {})
+        return {"path": path, "content": _file_content(file_data)}
+
+    def delete_thread(self, thread_id: str) -> dict[str, bool]:
+        session = self._sessions.pop(thread_id, None)
+        if session is None:
+            raise ThreadNotFound("thread not found")
+        session.close()
+        return {"deleted": True}
+
+    def _session(self, thread_id: str) -> AgentSession:
+        session = self._sessions.get(thread_id)
+        if session is None:
+            raise ThreadNotFound("thread not found")
+        return session
+
+
+def _file_entry(entry: Any) -> FileEntry:
+    path = entry.get("path", "") if isinstance(entry, dict) else getattr(entry, "path", "")
+    is_dir = entry.get("is_dir") if isinstance(entry, dict) else getattr(entry, "is_dir", False)
+    return FileEntry(path=str(path), type="directory" if is_dir else "file")
+
+
+def _file_content(file_data: Any) -> str:
+    if isinstance(file_data, dict):
+        return str(file_data.get("content", ""))
+    return str(getattr(file_data, "content", ""))
+
+
+def _content(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        return "\n".join(
+            str(item.get("text", item)) if isinstance(item, dict) else str(item) for item in value
+        )
+    return str(value or "")
+
+
+def _last_message_text(result: dict[str, Any]) -> str:
+    messages = result.get("messages", [])
+    if not messages:
+        return ""
+    last = messages[-1]
+    content = getattr(last, "content", None)
+    if content is None and isinstance(last, dict):
+        content = last.get("content")
+    return _content(content)

arena/validation_models.py

@@ -0,0 +1,22 @@
+"""Validator domain model import surface.
+
+New Validator modules should import from here instead of the shared model file.
+"""
+
+from __future__ import annotations
+
+from .models import (
+    Criteria,
+    ValidationCheck,
+    ValidationCheckResult,
+    ValidationCheckSource,
+    ValidationReport,
+)
+
+__all__ = [
+    "Criteria",
+    "ValidationCheck",
+    "ValidationCheckResult",
+    "ValidationCheckSource",
+    "ValidationReport",
+]