---
title: Harness Engineering — Agent Loops & Code-as-Tool-Interface
description: The agent harness layer — how the agent loop is built and how the model interacts with tools. Covers nanocodex (agent as in-process library), pi minimalism, Codex protocols, and code-as-tool-interface (Cloudflare Code Mode: tools as typed API, progressive discovery, V8 sandbox).
status: active
category: technical
tags: [harness, agent-loop, code-as-tool, codemode, cloudflare, nanocodex, pi, codex, tool-calling, typed-events, agent-infra]
draft: true
created: 2026-08-11
updated: 2026-08-11
origin: buzz://d8a718be-031f-4a6e-9f5c-a55466641654/c66f017974f748bd6db019c913d3a6f59de349e0cbd90ae38c222e9640521d63
---

# Harness Engineering — Agent Loops & Code-as-Tool-Interface

## Summary

The **harness** is the layer that runs the agent loop: it connects the model to tools, manages context, and streams events. Split out of durable-agent-runtime (2026-08-11) because it is a distinct lens — durability is about state; harness engineering is about the loop and the tool interface. Central 2026 finding: **code-as-tool-interface** — the harness should look like a programming environment, not a tool-call menu.

## Key Findings

- **Code as the tool interface is the converging pattern** (three independent sources):
  - Cloudflare Code Mode: MCP tools become a generated TypeScript API; the model writes code that calls it
  - nanocodex: typed `Turn`/`TurnResult` events over WebSocket beat stdout parsing
  - Prime Agent RLM: a persistent IPython REPL is the model's only tool
- **Why code beats direct tool calls**: LLMs are trained on real code, not synthetic tool-call tokens; intermediate results don't pollute context; composed logic is reusable.
- **Cloudflare Code Mode mechanics** (see analysis): tools as typed methods, progressive discovery (`codemode.search()` / `codemode.describe()`), execution safety via V8 isolate, six integration surfaces, experimental status.
- **Minimalism wins for small harnesses**: pi's 4-tool philosophy; don't load a huge MCP catalog into context.

## Sources

Primary: https://developers.cloudflare.com/agents/tools/codemode/ (2026-08-11); https://learn.chatgpt.com/docs/app-server; nanocodex repo; Prime Agent RLM (arXiv 2605.09998). See [[durable-agent-runtime/sources|Durable Agent Runtime sources]] for shared references.

## Detail Files

- [[harness-engineering/analysis|Analysis]] — code-as-tool-interface deep-dive, Cloudflare Code Mode mechanics, implications for our Effect TS stack

## Related Research

- [[agent-infra/index|Agent Infrastructure]] — umbrella topic
- [[durable-agent-runtime/index|Durable Agent Runtime]] — state/durability lens (formerly contained this topic)
- [[codex-app-server-byo-auth/index|Codex App Server & BYO Auth]] — Codex app-server as an embedding protocol surface

## Next Steps

- [ ] Prototype the "Code Mode pattern for Effect TS": expose our MCP/REST tools as a typed API agents write code against
- [ ] Evaluate which harness primitives (typed events, streaming items, code sandbox) belong in our own agent tooling