Deep-Dive DD-21 — Tau: The Educational Reference Harness

tau_coding  →  tau_agent  →  tau_ai

async def run_agent_loop(
    *, provider, model, messages, tools, system_prompt,
    max_turns, cancellation_token, steering_queue, follow_up_queue
) -> AsyncIterator[AgentEvent]:

AgentStart, AgentEnd, TurnStart, TurnEnd,
MessageStart, MessageDelta, MessageEnd,
ThinkingDelta,
ToolExecutionStart, ToolExecutionUpdate, ToolExecutionEnd,
Retry, QueueUpdate, Error

# Deep-Dive DD-21 — Tau: The Educational Reference Harness

**Course**: Master Course · **Deep-Dive**: DD-21 · **Duration**: 45 min · **Prerequisites**: Modules 0–12, DD-01 (Pi)

> *1,300+ stars. MIT. Python 3.12+. HuggingFace-hosted. The harness designed to be read like a textbook. ~300-line core loop, fully typed, three-layer separation enforced as a hard rule. τ = 2π — Pi, redone in Python.*

---

## The Subject

Tau (twotimespi.dev, github.com/huggingface/tau) is a Python reimplementation of Pi's minimalist coding-agent architecture. Authored by Alejandro AO, adopted under the HuggingFace org for visibility. Created June 2026 — 4 weeks old at time of writing, v0.1.5, shipping point releases every few days.

Tau's purpose is not to compete with Claude Code or Aider on capability. It competes on **legibility**. Every design decision serves a single goal: *this codebase should be readable by a student in an afternoon.* The three-layer separation, the typed event union, the stateless loop, the non-destructive session tree — these are the concepts Course 1 teaches abstractly, available here as code you can trace.

This deep-dive is structured differently from the others. Instead of scoring Tau against the 12-module rubric (it would score low on capability — 4 tools, no sandbox, no permissions), we study it as **the teaching companion to every module**. Where Module 1 teaches "the execution loop is the heartbeat," Tau shows you the heartbeat in 300 lines.

## Architecture — Three Layers, Hard Boundary

```
tau_coding  →  tau_agent  →  tau_ai
```

| Package | Role | What it is |
|---|---|---|
| `tau_ai` | Provider streaming | Translates OpenAI/Anthropic/Google/Mistral/Codex/OpenRouter/HF into one provider-neutral event stream |
| `tau_agent` | The reusable brain | The agent loop, harness, messages, tools, events, session primitives. **UI-free.** |
| `tau_coding` | The application | CLI (Typer), Textual TUI, the 4 built-in tools (read/write/edit/bash), provider config, sessions, slash commands, skills |

The load-bearing boundary, stated in README, AGENTS.md, and CONTRIBUTING.md: **`tau_agent` must not import Textual, Rich, CLI, config paths, or Tau-specific resources.** This is enforced by rule, not just convention. A whole ADR (`0001-use-textual-for-tui.md`) records the decision to keep Textual behind an adapter.

This is the cleanest illustration of Course 1 Module 0.1's three-job separation (loop → tools → safety) in any codebase studied. The boundary is a hard dependency wall.

## The Stateless Loop — Course 1 Module 1's Primary Code Example

`tau_agent/loop.py` is ~230 lines. The core is an async generator:

```python
async def run_agent_loop(
    *, provider, model, messages, tools, system_prompt,
    max_turns, cancellation_token, steering_queue, follow_up_queue
) -> AsyncIterator[AgentEvent]:
```

**Key design decisions:**

1. **The loop is stateless.** It takes the transcript (`messages`) as an argument and appends to it. The caller (the harness) owns all state. This makes the loop trivially testable with a `FakeProvider`.

2. **Events are the sole output.** The loop yields `AgentEvent` objects — never calls callbacks, never imports a UI library. Every frontend (print mode, Rich, Textual, JSON exporter, transcript renderer) consumes the same event stream.

3. **Tool execution is an isolation boundary.** Each tool call runs inside `try/except Exception` — a tool failure becomes `AgentToolResult(ok=False)`, never propagates. The loop cannot be crashed by a tool.

4. **Turn boundaries drain steering/follow-up queues.** After each model response + tool batch, the loop checks two queues: steering messages (inject mid-task, interrupt the current flow) and follow-up messages (inject only when the run would otherwise stop). This is the cleanest model of "user interrupts agent" in any harness studied.

Compare to DD-01 Pi's loop: same minimalist philosophy, same stateless design. Tau adds the typed event union, the steering/follow-up split, and transcript repair.

## The 14-Member Event Union — Course 1 Module 10's Observability Model

`tau_agent/events.py` defines a closed discriminated union:

```
AgentStart, AgentEnd, TurnStart, TurnEnd,
MessageStart, MessageDelta, MessageEnd,
ThinkingDelta,
ToolExecutionStart, ToolExecutionUpdate, ToolExecutionEnd,
Retry, QueueUpdate, Error
```

Every model is a frozen Pydantic dataclass with `ConfigDict(extra="forbid")`. This means:

- **The contract is closed.** No frontend can receive an event type it doesn't know about. Adding an event is a breaking change — enforced by the type system.
- **The contract is exhaustive.** A frontend's event handler must handle every case or explicitly ignore it. The type checker catches missing handlers.
- **Events ARE the observability layer.** You don't need a separate telemetry system — the event stream IS the trace. A JSON event consumer is a structured log. A Textual consumer is a live UI. A print consumer is a terminal transcript.

This is the strongest argument in the course for "events as the cross-layer contract" (Module 10). No other harness studied separates the event system this cleanly.

## Non-Destructive Compaction on an Append-Only Tree — Course 1 Module 3 & 8

Tau's session system (`tau_agent/session/`) is the most interesting session architecture in the roster:

1. **Sessions are append-only JSONL.** Entries are never rewritten or deleted.
2. **Entries are typed and discriminated** — `MessageEntry`, `ModelChangeEntry`, `CompactionEntry`, `BranchSummaryEntry`, `LabelEntry`, `LeafEntry`, `SessionInfoEntry`, `CustomEntry`.
3. **State is reconstructed by replay.** `SessionState.from_entries()` replays the entry list to derive the current message context. This is event-sourcing applied to agent sessions.
4. **Compaction is non-destructive.** A `CompactionEntry` carries `replaces_entry_ids` — during replay, those messages are swapped for a summary. The on-disk record stays intact. You can always re-derive the fuller history later.
5. **Branching via a tree of entries + leaf pointer.** A `BranchSummaryEntry` lets a conversation that returned from a branch inject a summary of that branch, so the model has context for the divergence without carrying the whole branch in context.

This is the strongest illustration of Course 1 Module 8 (State, Checkpointing & Multi-Session) in the roster. The append-only JSONL + replay reconstruction is exactly what Module 8 teaches — and here it's ~200 lines of readable Python.

## Transcript Repair After Interruption

A real production edge case most teaching agents skip:

When a run is cancelled mid-tool-call, the transcript has an assistant `tool_call` with no matching `tool_result`. OpenAI-compatible providers reject this transcript on the next request with a 400 error.

Tau's harness (`harness.py`) handles this: `_append_interrupted_tool_results()` synthesizes a `ToolResultMessage(ok=False, error="Tool call interrupted by user")` for every orphaned tool call before the next model request. This is the kind of detail that separates a teaching artifact from a toy.

## The Phase-by-Phase Build Journal

`dev-notes/architecture/phase-1` through `phase-25` document how the system was assembled, phase by phase. Each phase explains what was added, why, how it maps to Pi's design, and how to test it.

This is Course 1 Module 12 (Capstone) as a documented walkthrough. Students building their own harness can read how someone else did it — not the final product, but the process of getting there. No other harness in the roster offers this.

## Score: 24/60 (Educational, Not Production)

| Module | Score | Notes |
|---|---|---|
| M0 Concepts | 3/5 | Clean three-layer model, but minimal |
| M1 Loop | 5/5 | The reference implementation. Stateless + typed events + steering |
| M2 Tools | 2/5 | Only 4 tools (read/write/edit/bash). No schema validation beyond JSON |
| M3 Context | 4/5 | Non-destructive compaction tree is excellent |
| M4 Memory | 2/5 | Session-based only, no long-term memory store |
| M5 Sandbox | 1/5 | None. Bash runs whatever |
| M6 Permission | 1/5 | None. No approval gates |
| M7 Errors | 3/5 | Tool isolation (try/except → structured error), transcript repair |
| M8 State | 5/5 | Append-only JSONL + replay + branching. The reference |
| M9 Verification | 1/5 | None |
| M10 Observability | 5/5 | The event union IS the observability layer. The reference |
| M11 Security | 1/5 | None. No SECURITY.md |

### Architect's Verdict
> *Tau optimizes for legibility: the only harness where a student can read the loop, harness, tool registry, event system, and session tree in a single afternoon. Its value is pedagogical, not productive — score it low on capability, but understand that every concept Course 1 teaches has a readable implementation here. Use Tau as the teaching companion to every module: "read the source" is actually possible. Pin a commit for course material — the project is 4 weeks old and the API will move.*

### MLSecOps Relevance
> *Tau is the anti-NemoClaw. Where NemoClaw (DD-09) shows what production governance looks like, Tau shows what happens when you have none — bash runs whatever, no sandbox, no permissions, no SECURITY.md. This makes it the perfect "before" picture for Course 2B: here is a harness with zero defenses, now learn to attack it. Every 2B attack module can use Tau as the lab target — injection, memory poisoning, tool abuse, cascading failures all work against an unguarded harness.*

### 3 things Tau does better
1. **Legibility**: the only harness you can read in an afternoon. ~300-line loop, fully typed, phase-by-phase build journal.
2. **Event architecture**: the 14-member typed union with `extra="forbid"` is the cleanest cross-layer contract in the roster.
3. **Session architecture**: non-destructive compaction on an append-only JSONL tree with replay-based reconstruction. The reference for Module 8.

### 3 things to fix
1. **Add a sandbox**: bash runs whatever. At minimum, add a Docker option (like OpenCode's default).
2. **Add permission gates**: no approval on write/bash. Even Pi has basic confirmation.
3. **Add a SECURITY.md**: the project has no documented security model or disclosure process.

---

## References
1. **Tau source** — github.com/huggingface/tau (MIT, ~1.3k stars, v0.1.5).
2. **Tau docs** — twotimespi.dev (architecture, agent loop, design principles, session internals).
3. **Pi** — pi.dev, github.com/earendil-works/pi — the TypeScript original Tau reimplements.
4. **Module 1** — execution loop; Tau's `loop.py` as the primary code example.
5. **Module 3** — context management; non-destructive compaction.
6. **Module 8** — state/checkpointing; append-only JSONL + replay + branching.
7. **Module 10** — observability; the event union as the observability layer.
8. **Module 12** — capstone; the phase-by-phase build journal as reference.
9. **DD-01 (Pi)** — the original minimalist harness Tau is based on.
10. **DD-09 (NemoClaw)** — the anti-Tau: what production governance looks like.
11. **Course 2B** — Tau as the lab target for every attack module (unguarded harness).