c978db1437
- Add agent-infra umbrella topic (hub for state, harness, model-access, collaboration lenses) - Split harness-engineering out of durable-agent-runtime; fold in Cloudflare Code Mode finding - Narrow durable-agent-runtime to state/durability lens; retitle - Tag codex-app-server-byo-auth as agent-infra subtopic - Document umbrella-topic convention in README
46 lines
3 KiB
Markdown
46 lines
3 KiB
Markdown
---
|
|
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
|