add-harness-adapter
Skill22 starsChanged 2 months agoMITView on GitHub
Add or update an agent-top transcript adapter for a coding-agent harness (Aider, Copilot CLI, cursor-agent, Amp, a new Claude/Codex/Gemini/OpenCode format version). Use when asked to "support harness X", "read X's transcripts", "count X's tokens/cost/MCP calls", when a golden or drift test fails after an upstream release, or when a harness shows up in the table with no tokens, no cost, or the wrong attribution.
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- docs/llms.txtllms.txt
- agent-topSkill
- rust-best-practicesSkill
- tuff-capabilitiesSkill
- tuff-cli-guideSkill
- agent-topSkill
- tuff-cli-guideSkill
- write-changelogSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 3 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
Do not guess the layout from another harness.
- Very specific: line 41
Follow the constructor shape of the JSONL adapters: XTranscript::new(path).with_prices(table).with_spans(retention).
- Very specific: line 60
Read metadata fields only.
- Very specific: line 67
No file per session (a database, a server)?
- Very specific: line 99
No real session available?
- Very specific: line 102
Add a case to tests/drift.rs that renames the usage field the way an upstream release eventually will, and assert fields_unrecognised().
- Distinctive: line 105
When a golden test fails later, decide which it is: an intended parser change (re-record and review the diff, because that diff is every …
- Distinctive: line 118
Do not tag or release. Changes accumulate on main until the user explicitly asks for a release.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Adding a harness to agent-top
The collector never names a harness. Everything harness-specific lives behind
HarnessAdapter in crates/agent-top-core/src/harness/<name>.rs, so a new
harness is one module plus a short, fixed list of registrations. Work in that
order; the touchpoint checklist below is the part that gets forgotten.
1. Learn the format before writing any Rust
Do not guess the layout from another harness. Find the harness's own writer —
the recorder module in its npm package, its SQLite schema, its session
directory — and read it. Then write the findings into the module doc comment of
the new adapter first, with the version and the date verified, exactly as
harness/gemini.rs and harness/opencode.rs do. That comment is the contract
the parser is reviewed against, and AGENTS.md requires it to be updated
whenever the on-disk layout moves.
Answer these before coding:
- Where do transcripts live, and how does a path map back to a working directory?
- What is the record for one model response, and where is its token usage? Which numbers are cumulative and which are per-response (double counting lives here).
- Does the harness price the session itself? If so prefer its figure over our
table (
opencode.rsexplains why), and setunpriced_tokensto 0. - How are tool calls started and finished, and what pairs them (a call id)?
- Subagents: separate file, separate row in a table, or a flag on the message?
- Does the harness publish a registry of its processes (pid → session), or must a process be matched by cwd and start time?
- Does it log rate limits, MCP calls, or a web-search tool?
2. Implement the adapter
- New module
crates/agent-top-core/src/harness/<name>.rswith two types: anXAdapterimplementingHarnessAdapterand anXTranscriptimplementingSessionTracker. - Follow the constructor shape of the JSONL adapters:
XTranscript::new(path).with_prices(table).with_spans(retention). - Tail append-only logs with
jsonl::TailReader::read_new_lines(budget)and respectREFRESH_BUDGET_BYTES:refreshreturnstruewhen data is left, so a 100 MB transcript streams over several ticks instead of freezing a frame. - Fill
SessionSummaryand nothing else. Spans go throughSpanLog::open/close/open_kind(SpanKind::Turn,Inference,Tool) — never push spans directly, and pair by call id, because calls interleave. - Count
ParseHealthas you parse:billable_messagesfor every model response,usage_recordsfor every usage record found,empty_usage_recordsfor the ones that read as all-zero. This is what turns a silent upstream rename into a visible drift warning instead of a believable$0.00. - MCP calls go into
summary.mcp(aBTreeMap<String, McpUsage>keyed by server name), counted once per call. Do not also fold an MCP end-event intotool_callsif the call is already counted from its start record. - Attribution: exact only when the harness gives real evidence (a registry
entry, an open file handle). Otherwise return the matching
Attribution::CwdHeuristicvariant — AGENTS.md forbids presenting a guess as exact. - Read metadata fields only. No prompt text, no tool inputs, no tool output. The
one exception on record is Codex code mode, which takes the byte length of
nested output text as a weight and keeps only the number (docs/security.md,
"What it reads"); a new exception needs the same decision and the same doc
update. And nothing that writes, signals or connects: open the store read-only, the way
opencode.rs::open_roopens SQLite withSQLITE_OPEN_READ_ONLYso agent-top can never write to or lock the file the harness is using. - No file per session (a database, a server)? Mint a virtual path that stands
for one session and hand that to the rest of the system, as
opencode.rsdoes;SessionTracker::pathis an identifier, not necessarily a real file.
3. Register it — the checklist
harness/mod.rs:pub mod <name>;and aBox::new(<Name>Adapter::default())inadapters(). Order matters fordetectonly — a harness whose first lines look like another's must be asked first (Gemini before Claude).model.rs: aHarnessvariant and itslabel()string, if it is not already there (Aider,Copilot,Cursorexist with no adapter yet).process.rs::classify_agent: recognise the process. Node-hosted CLIs appear asnode <path>/cli.js, so match the script path too.prices.toml(crate root): every model the harness can run, with the date the price was checked. A missing model isunpriced_tokens, never a guess.collector.rsdetect test (the fixture list near the bottom of the file).- Docs:
README.md(the harness list in the intro, the bullets, and the per-harness support table near the end),crates/agent-top-core/README.md,docs/architecture.md,docs/accounting.mdif pricing differs, andCHANGELOG.md.
4. Golden fixture
Unit tests only prove the parser agrees with its author. Add a fixture:
- Capture a real session, then reduce it to the fields the parser reads — drop everything else rather than masking it. Audit the result for prompts, tool output, real paths and session ids before committing.
- Name it
<harness>-<version>.jsonlincrates/agent-top-core/tests/fixtures/, add a#[test]intests/golden.rsnext togemini_0_58, and record the expectation withUPDATE_GOLDEN=1 cargo test -p agent-top-core --test golden. - No real session available? Drive the harness's own recorder with a scripted
conversation and a fake clock, and check the driver in — see
gemini-0.58.drive.mjsand the fixtures README. - Add a case to
tests/drift.rsthat renames the usage field the way an upstream release eventually will, and assertfields_unrecognised().
When a golden test fails later, decide which it is: an intended parser change (re-record and review the diff, because that diff is every user's numbers) or a drift you did not intend.
5. Checks
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
cargo run -- --once # with a live session of the new harness, if possibleDo not tag or release. Changes accumulate on main until the user explicitly
asks for a release; the release runbook is in the internal handbook.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

