TL;DR
While the industry focuses on the "brain" (the Large Language Model), this paper shines a light on the "harness"—the critical software wrapper that turns model outputs into real-world actions. By formalizing 30 key design decisions into testable invariants, the author provides a rigorous engineering framework to prevent the "corner case" failures that plague modern AI agents.
What Problem Does This Paper Address?
In the world of AI agents, a language model on its own is just a text generator. To actually do something—like delete a file, browse the web, or run a shell command—it needs a harness. This is the program that manages the "turn loop": it sends requests to the model, parses the replies, executes tools, handles network drops, and maintains the conversation state.
The problem is that harness design is currently more "vibes" than engineering. Most design decisions are buried in code and rarely documented. Consequently, every developer ends up rediscovering the same painful corner cases: What happens if the model's reply is cut off mid-tool-call? How do we handle a "Stop" command during a long-running process? This paper seeks to move agent development from ad-hoc scripting to a systematic discipline.
Methods
The author introduces a structured approach to harness design centered around 30 Decision Cards categorized into six functional groups: The Turn, Failures, The Prompt, State, Permission, and Display.
Each card follows a strict format:
- The Decision: The specific choice the builder must make (e.g., "How a turn ends").
- Options: The trade-offs between different implementation paths.
- The Invariant: A universal property that should hold true regardless of the chosen option (e.g., "Every turn ends with exactly one recorded end reason").
- Corner Cases: The specific, often weird, scenarios that break the invariant.
- The Test: A concrete method to verify the invariant.
To support this, the paper defines a System Model with clear Trust Boundaries. It treats the model as an untrusted entity—its output is a request, not a decision. The author also introduces a testing methodology using "scripted providers" (mock LLMs that replay specific reply shapes) and fault injection to simulate edge cases like rate limits and malformed JSON deterministically.
Datasets
This is not a traditional machine learning paper, so it doesn't use standard training datasets like Common Crawl. Instead, it relies on:
- Crewroom: The author's own desktop agent harness, used as the primary "worked example."
- Reference Harnesses: Manual testing and observation of 10 other harnesses (both open-source and proprietary) to identify common patterns and failures.
- The Checklist: A newly introduced benchmark of 30 items used to evaluate the reliability and "correctness" of a harness's logic.
Key Insights and Ideas
- The "Two Readers" Problem: One of the most common failure modes occurs when two parts of a system interpret the same input differently. For example, if a security "checker" and the "shell" disagree on how to parse a command string, an agent might bypass a sandbox.
- Invariants over Benchmarks: While most AI research focuses on accuracy (did the agent solve the task?), this paper focuses on correctness (did the harness behave predictably?). An agent might be "smart" but still crash because the harness didn't handle a "discarded attempt" correctly.
- The "Behaviour Lock": The author advocates for recording every observable event in a turn (request bodies, log lines, exit codes) to create a "lock." When refactoring the harness, developers can ensure the system remains byte-identical in its behavior, catching regressions that traditional unit tests miss.
- Trust Boundaries: The paper systematizes the "attack surface" of an agent. It identifies six types of input that cross into the trusted base, including model output, tool results, and even "other agents' text."
Key Results
The paper identifies 83 specific invariant clauses for agent harnesses.
- Evidence Tags: Of these 83 clauses, 56 are "Tested" (verified in the author's harness), 12 are "Believed" (observed elsewhere or reasoned), and 15 remain "Open" (unresolved or known to be false).
- Self-Assessment: When applying the 30-item checklist to the author's own harness (Crewroom):
- 11 items held (e.g., tool call matching, reasoning isolation).
- 14 items did not hold (e.g., handling timed-out commands that continue running in the background).
- 5 items were not tested.
- Failure Taxonomy: The paper maps corner cases to six "cause classes," providing a diagnostic manual for builders to find "sibling" bugs once one is discovered.
Limitations and Future Work
- Single Rater: The evaluation was performed by the author alone; there was no second rater to provide an objective score.
- Scope: The paper explicitly does not evaluate "answer quality," cost, or performance. It is purely about the structural integrity of the harness.
- Platform Specificity: The findings are rooted in desktop/command-line harnesses; web-based or mobile-specific corner cases might differ.
- Future Directions: The author suggests several "open questions," such as how to handle approval requests that survive a system restart and whether look-alike (homoglyph) characters in model output should be normalized for security.
For those building the next generation of AI assistants, this paper serves as a vital "pre-flight checklist" to ensure your agent doesn't just think well, but acts reliably.
Summary updated