# stanford-iris-lab/meta-harness-tbench2-artifact architecture

> Architecture diagram of the GitHub repository stanford-iris-lab/meta-harness-tbench2-artifact, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stanford-iris-lab/meta-harness-tbench2-artifact
- Repository: https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact

## Overview

1. This repository is a thin Python agent harness, not a full application. Its job is to plug a custom agent into the Harbor/Terminus benchmark runtime for Terminal-Bench 2.0.

2. The core entry point is `agent.py`, which exposes the agent class used by Harbor (`AgentHarness` per the README). This is the main integration boundary between the repo and the external evaluation framework.

3. The runtime control flow is: Harbor launches the benchmark environment, imports `agent:AgentHarness`, and then drives the agent loop against Terminal-Bench tasks. The agent receives task context, interacts with the sandbox, and returns actions through the framework’s runloop.

4. The architecture is centered on a single LLM-backed decision loop. Model calls go to Anthropic Claude via the Harbor runner, with the API key supplied externally through `ANTHROPIC_API_KEY`.

5. A key repo-specific behavior is environment bootstrapping. Before the normal agent loop begins, the harness gathers a snapshot of the sandbox state—current working directory, file listing, available languages/tools, package managers, and memory—and injects that into the initial prompt.

6. That bootstrap step is the main data-flow enhancement in this repo: sandbox metadata flows into prompt construction, then into the model, reducing the need for the agent to spend early turns discovering basic environment facts.

7. Prompting is separated into template assets under `prompt-templates/`. The `terminus-kira.txt` template likely contains the system/instruction prompt inherited from Terminus-KIRA, with the harness adding environment-specific context on top.

8. `anthropic_caching.py` is a supporting subsystem for API efficiency and/or prompt reuse. It likely wraps Anthropic requests or message formatting to support cached prompt prefixes, which matters for repeated benchmark runs.

9. The project boundary is intentionally narrow: it does not implement the benchmark, terminal sandbox, or model orchestration itself. Those responsibilities live in Harbor and Terminal-Bench; this repo only customizes agent behavior and prompt initialization.

10. The external dependencies that shape the architecture are Harbor’s Terminus-2 framework, the Terminal-Bench 2.0 environment, and Anthropic’s Claude API. The repository is therefore best diagrammed as a small adapter layer between benchmark runner, sandbox environment, and LLM provider.

11. `pyproject.toml` defines the Python package/runtime metadata and dependencies, making this a standard Python-based harness distributed as code rather than as a standalone service.

12. In diagram terms, the important components are: Harbor benchmark runner, Terminal-Bench sandbox, this agent harness, prompt templates/cache helper, and Anthropic Claude. The main arrows are sandbox state into prompt construction, prompt into model calls, and model outputs back into terminal actions.

Main entry points: [`agent.py`](https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact/blob/main/agent.py) (Decision loop), [`anthropic_caching.py`](https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact/blob/main/anthropic_caching.py) (Caching helper), [`prompt-templates/terminus-kira.txt`](https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact/blob/main/prompt-templates/terminus-kira.txt) (Terminus prompt), [`pyproject.toml`](https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact/blob/main/pyproject.toml) (pyproject.toml)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["This repo"]
  node_agent_entry["agent.py<br/>agent entrypoint<br/>[agent.py]"]
  node_agent_harness["AgentHarness<br/>agent adapter<br/>[agent.py]"]
  node_env_bootstrap["Bootstrap<br/>env snapshot<br/>[agent.py]"]
  node_prompt_builder["Prompt builder<br/>prompt assembly<br/>[agent.py]"]
  node_decision_loop(("Decision loop<br/>LLM loop<br/>[agent.py]"))
  node_cache_helper["Caching helper<br/>anthropic wrapper"]
  node_prompt_template["Terminus prompt<br/>template asset<br/>[terminus-kira.txt]"]
  node_pyproject["pyproject.toml<br/>package metadata<br/>[pyproject.toml]"]
end

subgraph group_external["External systems"]
  node_harbor_runner["Harbor runner<br/>benchmark runtime"]
  node_terminal_bench["Terminal-Bench<br/>sandbox env"]
  node_claude_api["Claude API<br/>LLM provider"]
end

node_harbor_runner -->|"imports"| node_agent_entry
node_agent_entry -->|"exposes"| node_agent_harness
node_agent_harness -->|"snapshots"| node_env_bootstrap
node_env_bootstrap -->|"injects"| node_prompt_builder
node_prompt_template -->|"base prompt"| node_prompt_builder
node_prompt_builder -->|"feeds"| node_decision_loop
node_decision_loop -->|"calls"| node_claude_api
node_claude_api -->|"returns output"| node_decision_loop
node_decision_loop -->|"acts in sandbox"| node_terminal_bench
node_terminal_bench -->|"provides state"| node_env_bootstrap
node_cache_helper -.->|"optimizes"| node_decision_loop
node_agent_harness -.->|"packaged by"| node_pyproject

click node_agent_entry "https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact/blob/main/agent.py"
click node_agent_harness "https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact/blob/main/agent.py"
click node_env_bootstrap "https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact/blob/main/agent.py"
click node_prompt_builder "https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact/blob/main/agent.py"
click node_decision_loop "https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact/blob/main/agent.py"
click node_cache_helper "https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact/blob/main/anthropic_caching.py"
click node_prompt_template "https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact/blob/main/prompt-templates/terminus-kira.txt"
click node_pyproject "https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact/blob/main/pyproject.toml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent_entry,node_agent_harness,node_env_bootstrap,node_prompt_builder,node_decision_loop,node_cache_helper,node_prompt_template,node_pyproject toneBlue
class node_harbor_runner,node_terminal_bench,node_claude_api toneAmber
```

## Components

### This repo

Thin Python harness that adapts Harbor/Terminus to Terminal-Bench 2.0

- [agent.py](https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact/blob/main/agent.py): agent entrypoint · Repo boundary exposed to Harbor as AgentHarness · `agent.py`
- [AgentHarness](https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact/blob/main/agent.py): agent adapter · Main integration class that connects Harbor tasks to the repo's decision loop · `agent.py`
- [Bootstrap](https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact/blob/main/agent.py): env snapshot · Collects cwd, files, tools, package managers, languages, and memory before the first turn · `agent.py`
- [Prompt builder](https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact/blob/main/agent.py): prompt assembly · Combines template instructions with live sandbox context · `agent.py`
- [Decision loop](https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact/blob/main/agent.py): LLM loop · Turns task context and prompts into terminal actions across benchmark turns · `agent.py`
- [Caching helper](https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact/blob/main/anthropic_caching.py): anthropic wrapper · Supports Anthropic prompt reuse or cached message formatting · `anthropic_caching.py`
- [Terminus prompt](https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact/blob/main/prompt-templates/terminus-kira.txt): template asset · Base system/instruction prompt inherited from Terminus-KIRA · `prompt-templates/terminus-kira.txt`
- [pyproject.toml](https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact/blob/main/pyproject.toml): package metadata · Defines Python package metadata and runtime dependencies · `pyproject.toml`

### External systems

Benchmark runtime, sandbox, and model provider

- **Harbor runner**: benchmark runtime · Launches the benchmark, imports the agent entrypoint, and drives the runloop
- **Terminal-Bench**: sandbox env · Provides the terminal tasks, sandbox state, and action execution surface
- **Claude API**: LLM provider · Anthropic model endpoint used for decision making

## Connections

- Harbor runner → agent.py: imports · Harbor loads the agent entrypoint from this module
- agent.py → AgentHarness: exposes · Entry module publishes the AgentHarness class
- AgentHarness → Bootstrap: snapshots · Harness gathers sandbox metadata before starting the loop
- Bootstrap → Prompt builder: injects · Environment facts are added to the initial prompt
- Terminus prompt → Prompt builder: base prompt · Template provides the inherited instruction scaffold
- Prompt builder → Decision loop: feeds · Assembled prompt becomes input to the agent loop
- Decision loop → Claude API: calls · The loop sends prompts to Anthropic Claude through Harbor
- Claude API → Decision loop: returns output · Model responses are turned into actions or next-step reasoning
- Decision loop → Terminal-Bench: acts in sandbox · Generated actions are executed against the terminal environment
- Terminal-Bench → Bootstrap: provides state · Sandbox state is the source of the bootstrap snapshot
- Caching helper → Decision loop: optimizes · Helper supports cached prompt/message handling in repeated runs
- AgentHarness → pyproject.toml: packaged by · Project metadata defines how the harness is installed and run
