prefixlens 0.0.0-stage → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/CHANGELOG.md +28 -0
  2. package/LICENSE +21 -0
  3. package/README.md +179 -2
  4. package/SECURITY.md +82 -0
  5. package/SPEC.md +312 -0
  6. package/dist/adapters/claude-code.d.ts +2 -0
  7. package/dist/adapters/claude-code.js +759 -0
  8. package/dist/adapters/codex.d.ts +2 -0
  9. package/dist/adapters/codex.js +202 -0
  10. package/dist/adapters/index.d.ts +40 -0
  11. package/dist/adapters/index.js +43 -0
  12. package/dist/adapters/opencode.d.ts +3 -0
  13. package/dist/adapters/opencode.js +349 -0
  14. package/dist/adapters/otel.d.ts +2 -0
  15. package/dist/adapters/otel.js +170 -0
  16. package/dist/analyze.d.ts +162 -0
  17. package/dist/analyze.js +589 -0
  18. package/dist/assert.d.ts +86 -0
  19. package/dist/assert.js +179 -0
  20. package/dist/breaks.d.ts +64 -0
  21. package/dist/breaks.js +114 -0
  22. package/dist/canonical.d.ts +58 -0
  23. package/dist/canonical.js +362 -0
  24. package/dist/catalogue.d.ts +187 -0
  25. package/dist/catalogue.js +459 -0
  26. package/dist/cli.d.ts +2 -0
  27. package/dist/cli.js +347 -0
  28. package/dist/diff.d.ts +45 -0
  29. package/dist/diff.js +601 -0
  30. package/dist/index.d.ts +37 -0
  31. package/dist/index.js +24 -0
  32. package/dist/lens.d.ts +62 -0
  33. package/dist/lens.js +62 -0
  34. package/dist/params.d.ts +29 -0
  35. package/dist/params.js +72 -0
  36. package/dist/pricing-command.d.ts +13 -0
  37. package/dist/pricing-command.js +198 -0
  38. package/dist/pricing.d.ts +135 -0
  39. package/dist/pricing.js +263 -0
  40. package/dist/printable.d.ts +10 -0
  41. package/dist/printable.js +27 -0
  42. package/dist/provider.d.ts +6 -0
  43. package/dist/provider.js +18 -0
  44. package/dist/proxy.d.ts +53 -0
  45. package/dist/proxy.js +155 -0
  46. package/dist/record/exchange.d.ts +86 -0
  47. package/dist/record/exchange.js +232 -0
  48. package/dist/record/fetch.d.ts +23 -0
  49. package/dist/record/fetch.js +96 -0
  50. package/dist/record/recorder.d.ts +95 -0
  51. package/dist/record/recorder.js +254 -0
  52. package/dist/report/format.d.ts +31 -0
  53. package/dist/report/format.js +99 -0
  54. package/dist/report/html.d.ts +7 -0
  55. package/dist/report/html.js +223 -0
  56. package/dist/report/json.d.ts +13 -0
  57. package/dist/report/json.js +6 -0
  58. package/dist/report/terminal.d.ts +9 -0
  59. package/dist/report/terminal.js +150 -0
  60. package/dist/runtime/server.d.ts +37 -0
  61. package/dist/runtime/server.js +175 -0
  62. package/dist/runtime/sqlite.d.ts +7 -0
  63. package/dist/runtime/sqlite.js +16 -0
  64. package/dist/textdiff.d.ts +32 -0
  65. package/dist/textdiff.js +157 -0
  66. package/dist/trace.d.ts +172 -0
  67. package/dist/trace.js +335 -0
  68. package/dist/usage.d.ts +4 -0
  69. package/dist/usage.js +84 -0
  70. package/dist/version.d.ts +1 -0
  71. package/dist/version.js +4 -0
  72. package/package.json +73 -4
  73. package/pricing.json +175 -0
package/SPEC.md ADDED
@@ -0,0 +1,312 @@
1
+ # prefixlens trace format, version 1.3
2
+
3
+ This document specifies the trace format that prefixlens reads. A harness in any language can write it directly; prefixlens's own log adapters write it too. The key words MUST, SHOULD and MAY are used as in RFC 2119.
4
+
5
+ **Versions and compatibility.** Records carry the major version in `v`, which is `1` for every 1.x version of this document. A minor version only adds optional fields and hint kinds, so:
6
+
7
+ - every 1.0, 1.1 and 1.2 trace is a valid 1.3 trace and reads exactly as before;
8
+ - an older reader reads a newer trace, ignoring what it does not know (section 2, section 6). A 1.0 reader will then report a declared intentional break (section 6.1) as an ordinary miss: the trace degrades to what it would have said without the declaration, never to something less safe.
9
+
10
+ Version 1.3 adds the optional `deferred` block field (section 4.1) and the `{"system": n}` form of a `prefix_break` hint's `after` (section 6.1). A reader from before them compares a deferred tool like any other tool block, and drops a hint whose `after` it does not know, with a warning, so the miss is reported rather than excused: both are what that reader did before, and neither is less safe. It also says in section 4.3 where a top-level Anthropic `cache_control` goes (a `breakpoint`, not `params`), and in section 4.2 what an OpenAI `item_reference` block is.
11
+
12
+ Version 1.2 adds the optional `interrupted` and `billing` record fields (section 2), the block fields `unknown` (section 4.1) and `elided` (binary-data elision, section 4.5), the optional `cache_write_12h_tokens` usage field (section 3), the `tools_changed` hint (section 6), and OpenAI's explicit cache breakpoints (`prompt_cache_breakpoint`, removed from content and recorded as `breakpoint`, section 4.3; `prompt_cache_options`, section 8). A block that carried `prompt_cache_breakpoint` hashes differently than a 1.1 writer that kept the marker would have hashed it; no other block changes.
13
+
14
+ Version 1.1 adds the `prefix_break` hint (section 6.1), states the canonical form of every `cache_control` marker and of a non-string system prompt (section 4.3), and documents which request parameters each provider caches on (section 8.1).
15
+
16
+ A trace records the model calls an agent made, one record per call, so that each call can be compared with the call before it. The comparison answers two questions: did the call read from the prompt cache what the previous call left there, and if not, which part of the request changed.
17
+
18
+ ## 1. File
19
+
20
+ - A trace is a text file in UTF-8. Each line is one JSON object (JSON Lines). Blank lines are ignored.
21
+ - Each line describes one model call: one HTTP request to a model API and its response.
22
+ - Records SHOULD be written in the order the requests were sent. Readers process records in file order.
23
+ - A trace MAY hold several sessions and several lanes (section 7). Records from different lanes MAY be interleaved.
24
+ - Writers SHOULD append to the file as calls complete; a trace is valid at every line boundary.
25
+ - The suggested file extension is `.trace.jsonl`.
26
+
27
+ ## 2. Record
28
+
29
+ | Field | Type | Required | Meaning |
30
+ |---|---|---|---|
31
+ | `v` | integer | yes | Major format version. Always `1` for this document (1.3); see "Versions and compatibility". |
32
+ | `ts` | string | yes | When the request was sent, as an RFC 3339 timestamp with a time zone, e.g. `"2026-01-01T10:00:00.000Z"`. Use the request start, not the response end: cache lifetimes run from the start of the request that wrote or read the entry. |
33
+ | `provider` | string | yes | Whose caching rules apply: `"anthropic"`, `"openai"` or `"gemini"`. Other values are allowed (e.g. a gateway id); readers then fall back to defaults. For a model reached through a gateway or cloud (Bedrock, Vertex, OpenRouter), use the provider that built the model. |
34
+ | `model` | string | yes | Model id as sent in the request, e.g. `"claude-opus-5-5"`. |
35
+ | `fidelity` | string | yes | `"full-request"` or `"usage-only"`. See section 5. |
36
+ | `usage` | object | yes | Token counts from the response. See section 3. |
37
+ | `request` | object | when `fidelity` is `"full-request"` | `{ "reuse"?: integer, "blocks": [Block, ...] }`: the request as ordered blocks (section 4), optionally starting with blocks reused from the previous full request in the same lane (section 4.6). MUST be absent or ignored for `"usage-only"`. |
38
+ | `params` | object | no | Every request field that is not the model, tools, system prompt or messages, for example `{"max_tokens": 32000, "thinking": {"type": "adaptive"}, "tool_choice": {"type": "auto"}}`. Leave out transport-only fields (`stream`, `stream_options`). Writers SHOULD also leave out fields that identify a person, account, device or installation and are not model input (section 8.1, "Identifying fields"): `metadata` (Anthropic's `metadata.user_id`, where Claude Code puts its account id, a persistent device id and the session id; OpenAI's developer key-value pairs), `user`, `safety_identifier`, and client metadata such as Codex's `client_metadata` (a copy of its own request headers: an installation id, per-turn ids, local paths); a writer MAY keep them when its user asks. Keep `prompt_cache_key`: it is a cache-routing key (a harness may derive it from a session or user id). Never include credentials or headers. Write parameters as sent, including ones the provider does not cache on: section 8.1 decides which ones matter, so a writer does not need to. A parameter whose value is not known MAY be left out. |
39
+ | `id` | string | no | An identifier for the call, unique within the trace (a request id or response id). |
40
+ | `session` | string | no | The conversation this call belongs to. |
41
+ | `lane` | string | no | A sequence of calls within the session that build on each other, e.g. `"main"` or a subagent id. Default `"main"`. See section 7. |
42
+ | `cache_ttl_seconds` | integer | no | Cache lifetime that applied to the prefix this call wrote, in seconds. For Anthropic, the TTL of the last `cache_control` breakpoint: `300` for the default 5 minutes, `3600` for `"ttl": "1h"`. For OpenAI (GPT-5.6 and later), the minimum lifetime the request set: in implicit mode `prompt_cache_options.ttl`; in explicit mode (`prompt_cache_options.mode: "explicit"`) the `ttl` of the last `prompt_cache_breakpoint`, else `prompt_cache_options.ttl`: `1800` for `"30m"`, `43200` for `"12h"`. Omit when unknown; readers use the model's or provider's default. |
43
+ | `hints` | array | no | Facts the harness knows about what happened before this call, including intentional breaks it declares. See section 6. |
44
+ | `headers` | object of strings | no | Request headers that route the request to a cache or change what is cached, lowercase names, e.g. `{"session-id": "…"}` (OpenAI's ChatGPT sign-in flow routes its prompt cache by `session-id`), `anthropic-beta`, `anthropic-version`, `openai-beta`. Writers MUST write only headers known not to be credentials: never `authorization`, `x-api-key`, cookies or account ids. prefixlens reports a miss with the prefix intact and a changed `session-id` as a routing change, not a provider-side miss. |
45
+ | `interrupted` | boolean | no | 1.2. `true` when the response ended before its final event: the client disconnected or the connection broke. `usage` then holds what the response reported before it ended; its input side (`input_tokens`, `cache_read_tokens`, `cache_write_tokens`) MUST be final, and `output_tokens` is a lower bound (Anthropic reports the input side in its first stream event, so a cut-off Anthropic call can be recorded; an OpenAI stream reports usage only at its end, so a cut-off one cannot). A writer that does not have final input-side counts MUST NOT write the record. Readers count the call in hit rates and miss arithmetic as usual and treat its output tokens and cost as lower bounds. Absent means `false`. |
46
+ | `billing` | string | no | 1.2. How the call was billed: `"per_token"` (API billing, where list prices are what was charged before discounts) or `"subscription"` (a plan such as a Claude plan or ChatGPT sign-in, where list prices are only a comparison). Set it only when the writer knows; absent means unknown, and readers MUST NOT assume either. |
47
+ | `source` | object | no | Free-form provenance, e.g. `{"adapter": "claude-code", "version": "2.1.322"}` or `{"harness": "myagent", "version": "0.3.0"}`. Readers do not interpret it. The one exception is prefixlens reading its own older traces: its recorders once marked a cut-off call as `{"recorder": "…", "complete": false}` here, before `interrupted` existed, and it still reads that as `interrupted`. |
48
+
49
+ Readers MUST ignore fields they do not know. Writers MUST NOT put API keys, auth headers or other credentials in any field.
50
+
51
+ ## 3. Usage
52
+
53
+ | Field | Type | Required | Meaning |
54
+ |---|---|---|---|
55
+ | `input_tokens` | integer ≥ 0 | yes | Input tokens that were neither read from nor written to the cache (billed at the base input price). |
56
+ | `cache_read_tokens` | integer ≥ 0 | yes | Input tokens read from the cache. |
57
+ | `cache_write_tokens` | integer ≥ 0, or `null` | yes | Input tokens written to the cache, as the provider reported them. `null` when the provider does not report writes (Gemini; OpenAI before GPT-5.6). Use `0`, not `null`, when an explicit-caching provider wrote nothing. A figure from an implicit-caching provider (OpenAI, Gemini) is a billing fact, not a measure of what was cached: section 8. |
58
+ | `cache_write_1h_tokens` | integer ≥ 0 | no | The part of `cache_write_tokens` written with a 1-hour TTL (Anthropic; priced differently from 5-minute writes). |
59
+ | `cache_write_12h_tokens` | integer ≥ 0 | no | 1.2. The part of `cache_write_tokens` written with a 12-hour lifetime (OpenAI; priced differently from the default 30-minute writes). OpenAI Responses: `input_tokens_details.cache_write_tokens_details.ttl_12h_tokens`. Omit when the provider does not report the split. |
60
+ | `output_tokens` | integer ≥ 0 | yes | All billed output tokens, including reasoning. |
61
+ | `reasoning_tokens` | integer ≥ 0 | no | The part of `output_tokens` spent on reasoning. |
62
+ | `reported_cost` | number ≥ 0 | no | What the harness itself recorded this call cost, in USD. prefixlens prices calls from its own table and shows this only for comparison. |
63
+
64
+ The prompt size of a call is `input_tokens + cache_read_tokens + (cache_write_tokens or 0)`.
65
+
66
+ How to fill it from each provider's response:
67
+
68
+ | Provider | `input_tokens` | `cache_read_tokens` | `cache_write_tokens` | `output_tokens` |
69
+ |---|---|---|---|---|
70
+ | Anthropic Messages | `usage.input_tokens` (already excludes cache) | `usage.cache_read_input_tokens` | `usage.cache_creation_input_tokens`; `cache_write_1h_tokens` = `usage.cache_creation.ephemeral_1h_input_tokens` | `usage.output_tokens` |
71
+ | OpenAI Chat Completions | `prompt_tokens − prompt_tokens_details.cached_tokens − prompt_tokens_details.cache_write_tokens` | `prompt_tokens_details.cached_tokens` | `prompt_tokens_details.cache_write_tokens` when the response has the field (zero included), else `null` | `completion_tokens`; `reasoning_tokens` = `completion_tokens_details.reasoning_tokens` |
72
+ | OpenAI Responses | `input_tokens − input_tokens_details.cached_tokens − input_tokens_details.cache_write_tokens` | `input_tokens_details.cached_tokens` | `input_tokens_details.cache_write_tokens` when the response has the field (zero included), else `null` | `output_tokens`; `reasoning_tokens` = `output_tokens_details.reasoning_tokens` |
73
+ | Gemini | `promptTokenCount − cachedContentTokenCount` | `cachedContentTokenCount` | `null` | `candidatesTokenCount + thoughtsTokenCount` |
74
+
75
+ Anthropic caches only up to explicit `cache_control` breakpoints and reports writes; a response without `cache_creation_input_tokens` wrote nothing. OpenAI caches prompt prefixes automatically once the prompt is about 1024 tokens or longer, in 128-token steps; it reports reads, and from GPT-5.6 on, which bills cache writes, also writes. Some OpenAI backends report a write field that is always zero (the ChatGPT sign-in backend does, while caching normally); record it as reported. Gemini's implicit caching reports only reads.
76
+
77
+ When a streamed response reports usage in several events, record the final totals.
78
+
79
+ ## 4. Blocks
80
+
81
+ A full request is a list of blocks in the order the provider assembles the prompt prefix. Each block is one tool definition, one part of the system prompt, or one message.
82
+
83
+ ### 4.1 Block object
84
+
85
+ | Field | Type | Required | Meaning |
86
+ |---|---|---|---|
87
+ | `kind` | string | yes | `"tool"`, `"system"` or `"message"`. |
88
+ | `hash` | string | yes, unless `content` is present | Lowercase hex SHA-256 of the canonical JSON of `content` (section 4.4). Readers compute it when absent. |
89
+ | `content` | any JSON value | no | The block as sent, in the canonical form of section 4.3. May be omitted (section 4.5). |
90
+ | `key` | string | no | The tool name for tools; the role for messages (`"user"`, `"assistant"`, `"tool"`, ...). Used in explanations only; not hashed. |
91
+ | `breakpoint` | boolean | no | `true` when a cache breakpoint (Anthropic `cache_control`, OpenAI `prompt_cache_breakpoint`) was set on this block or on a part inside it. |
92
+ | `elided` | boolean | no | 1.2. `true` when binary data inside `content` was replaced by its digest and size (section 4.5). `hash` is then still that of the content as sent, and is required. |
93
+ | `deferred` | boolean | no | 1.3. `true` on a tool block the request sent with deferred loading (Anthropic: `defer_loading: true` on the tool). The provider does not render such a tool into the prompt until tool search returns it, so it is not part of the cached prefix: adding, removing or editing one cannot cost cached tokens. Writers SHOULD still list it, in its place among the tools and hashed as sent, so the trace shows which tools were deferred. Readers MUST leave `deferred` blocks out when they compare two requests, and count blocks without them: block numbers in a report, an integer `after` (section 6.1) and the position of the last breakpoint all refer to the request's blocks with the deferred ones removed. `request.reuse` (section 4.6) counts every listed block, deferred ones included. Only a `tool` block may be `deferred`. A reader that does not know the field compares the block like any other tool, as before it existed. |
94
+ | `unknown` | boolean | no | 1.2. `true` when the writer knows that a block was sent at this position but not what it held. `hash` is then a placeholder rather than a SHA-256 (e.g. `"unknown:claude-code-billing-attribution"`), the same on every record for which the writer cannot tell the block apart, and `content` MUST be absent; `key` MAY name what the block is. Placing it keeps every other block, and every breakpoint, at the position it was sent at, so a trace from this writer and one from a recorder of the same call agree on every block but this one. A change confined to an unknown block cannot be seen: a miss it caused reads as one with the prefix intact. |
95
+
96
+ ### 4.2 Order
97
+
98
+ All tool blocks come first, then all system blocks, then all message blocks. Readers MUST reject a record whose blocks are out of that order.
99
+
100
+ Within each group, blocks keep the order of the request:
101
+
102
+ | Provider | tool blocks | system blocks | message blocks |
103
+ |---|---|---|---|
104
+ | Anthropic | each element of `tools` | each element of `system` (a string `system` is one block) | each element of `messages` |
105
+ | OpenAI Chat | each element of `tools` (and legacy `functions`) | each leading `messages` element whose role is `system` or `developer` | the other `messages` elements |
106
+ | OpenAI Responses | each element of `tools` | `instructions` (one block, absent when `instructions` is absent or `null`), then each leading `input` item whose role is `system` or `developer` | the other `input` items |
107
+ | Gemini | each entry of `tools[].functionDeclarations`; other tool entries (e.g. `{"googleSearch": {}}`) whole | each part of `systemInstruction.parts` | each element of `contents` |
108
+
109
+ An OpenAI Responses `item_reference` input item (`{"type": "item_reference", "id": "…"}`, earlier output the request names by id and the provider fills in from what it stored) is one message block like any other input item, with `key` `"item_reference"` and the reference as its content. Two requests compare equal on it when the id is the same. The item it names was not in the request: its content and its size are unknown to the trace, and a reader SHOULD say so when it reports on a request that has one (prefixlens counts such blocks in the assertion's message and notes them in a report). A reader MUST NOT fetch or guess the content.
110
+
111
+ "Leading" means before the first element with any other role; a system or developer message later in the conversation is a message block, so the order rule holds.
112
+
113
+ A tool sent with deferred loading keeps its place among the tool blocks and is marked `deferred` (section 4.1); it is listed, but is not part of the prefix.
114
+
115
+ The tools-before-system order matches Anthropic's documented render order (tools, then system, then messages). For OpenAI and Gemini the provider's internal order is not documented; the order above is a convention, and since a change anywhere in the prefix invalidates what follows it, the first changed block still identifies the cause.
116
+
117
+ ### 4.3 Canonical content
118
+
119
+ `content` is the block as the provider received it, with two normalizations, so that harmless representation changes do not look like edits:
120
+
121
+ 1. **Remove cache markers.** Delete the `cache_control` key from the block object itself and from each element of its message parts (the `content` array; for Gemini, the `parts` array). Do not delete keys at other depths. Breakpoints move between calls without changing what is cached; record them in `breakpoint` instead. This applies to every block of every provider: tools, system parts and messages alike. Only Anthropic defines `cache_control`, but OpenAI-compatible gateways accept the same marker in OpenAI-format bodies (on tools as well as messages) and forward it, and it moves between calls in the same way. A marker left in would make a moved breakpoint read as an edited tool or message.
122
+ An Anthropic request may also carry `cache_control` at its top level (request-level, or automatic, caching): Anthropic then places the breakpoint on the last cacheable block of the request and moves it forward as the conversation grows. It is not a request parameter: leave it out of `params` and set `breakpoint` on the last block. Its `ttl` sets `cache_ttl_seconds` like any other breakpoint's, as the last one in prefix order.
123
+ OpenAI's explicit breakpoints are removed the same way: delete `prompt_cache_breakpoint` from an OpenAI message or input item and from each element of its `content` array and, for a Responses `function_call_output`, of its `output` array, and record it in `breakpoint`. OpenAI documents the marker on content parts of input messages in the Responses API (not on `instructions` or tools); its SDK types also allow it on Chat Completions content parts, which are treated alike.
124
+ 2. **Use the part form for text.** When a message's `content` is a string, replace it with a one-element array holding a text part: `[{"type": "text", "text": "<string>"}]` for Anthropic and OpenAI Chat; `{"type": "input_text", ...}` (or `"output_text"` for assistant messages) for OpenAI Responses. An Anthropic `system` string becomes one block with content `{"type": "text", "text": "<string>"}`; an OpenAI Responses `instructions` string becomes one block with the same content.
125
+ 3. **Keep undocumented system forms whole.** An Anthropic `system` or OpenAI Responses `instructions` that is `null` or absent gives no block. One that is neither a string nor (for Anthropic `system`) an array is not a documented form; it becomes one system block whose content is the value as sent. It is never dropped: the provider received it, so a change to it must show.
126
+
127
+ Everything else is kept as sent, including key order (which does not affect the hash) and unknown fields.
128
+
129
+ ### 4.4 Hash
130
+
131
+ ```
132
+ hash = lowercase_hex( SHA-256( UTF-8( canonical_json(content) ) ) )
133
+ ```
134
+
135
+ `canonical_json` is the JSON Canonicalization Scheme (RFC 8785): no whitespace; object members sorted by key, comparing keys as sequences of UTF-16 code units; strings escaped as ECMAScript `JSON.stringify` escapes them (`\"`, `\\`, `\b`, `\f`, `\n`, `\r`, `\t`, `\u00XX` for other control characters, everything else literal); numbers in ECMAScript shortest round-trip form (`1`, `1.5`, `1e+21`, `-0` written as `0`). `NaN` and infinities are not allowed.
136
+
137
+ In JavaScript this is `JSON.stringify` applied to a copy with keys sorted recursively. In Python, `json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)` gives the same bytes for content without floats that need ECMAScript formatting and without non-BMP keys that sort differently in UTF-16.
138
+
139
+ Test vectors:
140
+
141
+ | content | hash |
142
+ |---|---|
143
+ | `{"a":1}` | `015abd7f5cc57a2dd94b7590f04ad8084273905ee33ec5cebeae62276a97f862` |
144
+ | `{"type":"custom","name":"read_file"}` | `5d364be90495295000470579a9553503093c9e3b7d035f94f0626e24de3693e1` |
145
+ | `{"role":"user","content":[{"type":"text","text":"hi"}]}` | `da3ac0b4d79dbe28c3c6684e1e4d037992df0e519e410c56436a23ecadf5c3c1` |
146
+
147
+ Two blocks are the same if and only if their hashes are equal. When a block carries both `hash` and `content`, readers SHOULD warn if they disagree and use `hash`.
148
+
149
+ ### 4.5 Omitting content
150
+
151
+ `content` MAY be omitted from a block, leaving `kind`, `hash` and optionally `key` and `breakpoint`:
152
+
153
+ - **Deduplication.** A writer SHOULD write each distinct block's content only the first time its hash appears in the file, and omit it from later blocks with the same hash. Readers restore omitted content from the earliest earlier line with the same hash. Without this, a full-request trace grows with the square of the conversation length, since each call repeats the whole prefix.
154
+ - **Redaction.** A writer MAY omit content it does not want stored (secrets, private code). A hash-only block still locates the first changed block exactly; only the text diff is lost. A writer that redacts MUST still compute the hash over the real canonical content.
155
+
156
+ - **Binary data.** A writer SHOULD replace the base64 data of images, documents, audio and files inside `content` with a string `"<binary MEDIA_TYPE, N bytes, sha256 HEX>"` (`MEDIA_TYPE` is omitted when the part does not name one; `N` is the size of the decoded bytes; `HEX` is the lowercase hex SHA-256 of the base64 text as sent), and set `"elided": true` on the block. The block's `hash` MUST still be computed over the content as sent, so a block written this way and the same block written in full have the same hash and compare equal, and a changed image still changes it. The parts are, per provider: an Anthropic part whose `source` has `"type": "base64"` (`source.data`; images and documents, also inside `tool_result` content); OpenAI Responses `input_image` (`image_url` when it is a `data:` URL) and `input_file` (`file_data`); Chat Completions `image_url` (`image_url.url`, a `data:` URL), `input_audio` (`input_audio.data`) and `file` (`file.file_data`); Gemini `inlineData` (`data`). A URL that is not a `data:` URL is not binary data and is kept. Readers MUST NOT check `hash` against the content of an `elided` block, and MAY name a change in such a block by the digests.
157
+
158
+ A hash-only block whose hash never appears with content is valid; it is treated as redacted.
159
+
160
+ ### 4.6 Reusing the previous request's prefix
161
+
162
+ Even with content deduplicated, listing every block's hash on every line makes a long session's trace grow with the square of its length. A record MAY therefore set `request.reuse` to a non-negative integer N. Its full block list is then the first N blocks of the previous `"full-request"` record in the same lane (section 7), exactly as that record's blocks were resolved (including `key` and `breakpoint`), followed by the blocks in `request.blocks`.
163
+
164
+ - "Previous" means the closest earlier line in the file with the same `session` and `lane` and `fidelity: "full-request"`; usage-only records in between are skipped.
165
+ - N MUST NOT exceed that record's block count; if there is no such record, N MUST be 0. Readers MUST reject the record otherwise.
166
+ - The block-order rule of section 4.2 applies to the resolved list.
167
+ - A writer that reuses a block with a different `breakpoint` (or `deferred`) value than before must list that block instead, since reuse copies the flags. In practice: reuse the longest leading run of blocks whose `hash`, `kind`, `key`, `breakpoint` and `deferred` are all unchanged.
168
+ - Omitting `reuse` (or writing 0) and listing every block is always valid.
169
+
170
+ ## 5. Fidelity
171
+
172
+ - **`"full-request"`**: `request.blocks` lists every tool, system part and message the provider received, in order. With two consecutive full-request records in a lane, a reader can prove whether the earlier request is an unchanged prefix of the later one and name the first block that differs. A writer that rebuilds requests from a log, rather than recording the request it sent, SHOULD write `"full-request"` only when it can show the rebuild is exact, marking any block it knows was sent but cannot rebuild as `unknown` (section 4.1), and `"usage-only"` otherwise. prefixlens's Claude Code importer matches the digest Claude Code logs of each request as Claude Code built it, which proves the tools, the logged system parts, the messages, the parameters and the breakpoints; Claude Code's transport then adds a first system block it does not log (a billing-attribution line that differs per session), which the importer writes as an unknown block, and sends the logged `betas` parameter as the `anthropic-beta` header, which the importer writes in `headers`. Changes a provider makes after receiving the request, such as server-side context editing, are outside the trace.
173
+ - **`"usage-only"`**: only the response usage is known (plus `model`, `ts` and optionally `params` and `hints`). Hit rates, lost tokens and costs are exact. The cause of a miss cannot be proven; readers may infer one from a model change, the time gap against the TTL, and hints, and MUST label such causes as inferred. prefixlens infers, in this order: a model change; for a call that read nothing, sent later than the TTL after the previous call, a likely expiry (naming any hint beside it); a declared break or hint; a likely expiry for a partial miss with no hint; otherwise the cause is unknown.
174
+
175
+ A trace may mix both. A comparison between a full-request record and a usage-only record is treated as usage-only.
176
+
177
+ ## 6. Hints
178
+
179
+ Optional facts from the harness's own log, used to explain usage-only misses and to disambiguate full-request diffs. Each hint is `{"kind": "<kind>", "detail": "<optional text>"}`. Attach a hint to the first call made after the event.
180
+
181
+ | kind | meaning |
182
+ |---|---|
183
+ | `compaction` | History was summarized or replaced before this call. |
184
+ | `compaction_call` | This call is the compaction (summarization) request itself. |
185
+ | `tool_output_pruned` | Earlier tool outputs were cleared or shortened in history before this call. |
186
+ | `agent_switch` | The agent or mode changed before this call (its tools and system prompt usually differ). `detail` like `"build → plan"`. |
187
+ | `model_switch` | The user or harness changed models before this call. Also declares an intentional break (section 6.1). |
188
+ | `prefix_break` | The harness broke its own prefix on purpose before this call. Version 1.1; section 6.1. |
189
+ | `tools_changed` | The tool list sent with this call differs from the previous call's in its lane: tools added, removed, or a definition changed. `detail` names them, e.g. `"+1 tool (web_search); 2 → 3 tools"`. For usage-only writers that know the tool list by name and hash without knowing the request (the Codex importer). Version 1.2. |
190
+
191
+ A `compaction` hint also declares an intentional break (section 6.1). `agent_switch`, `tools_changed`, `tool_output_pruned` and `compaction_call` only name what happened: a mode switch that changes the tool list, or a pruned tool output, is the kind of change prefixlens exists to find, so it stays a miss unless the harness declares it with `prefix_break`.
192
+
193
+ Readers MUST ignore hint kinds they do not know.
194
+
195
+ ### 6.1 Declaring an intentional break
196
+
197
+ A harness sometimes breaks its prefix on purpose: it compacts history and rebuilds its instructions, the user reverts to an earlier point, a refused exchange is left out of history, the user picks another model or reasoning effort. The miss that follows is real and costs money, but it is not a bug. The harness declares it on the first call after the event with a `prefix_break` hint:
198
+
199
+ ```json
200
+ {"kind": "prefix_break", "reason": "revert", "detail": "reverted to message 12"}
201
+ ```
202
+
203
+ | Field | Type | Required | Meaning |
204
+ |---|---|---|---|
205
+ | `kind` | string | yes | `"prefix_break"`. |
206
+ | `reason` | string | yes | Why. One of the reasons below, or another short word. |
207
+ | `after` | `"start"`, `"tools"`, `"system"`, `{"system": n}`, `{"message": n}`, or an integer ≥ 0 | no | The last part of the previous request that the break leaves unchanged: nothing (`"start"`), the tools, the tools and system prompt, the tools and the first n system parts (`{"system": n}`, version 1.3, for a harness that rewrites a later system part on purpose, such as working memory; an n beyond the system prompt keeps all of it), the tools and system prompt plus messages 1..n, or the first n blocks. Default: set by `reason`, below. |
208
+ | `detail` | string | no | Free text for people, e.g. `"high → low"`. |
209
+
210
+ | `reason` | for | default `after` |
211
+ |---|---|---|
212
+ | `compaction` | history summarized or replaced (the harness may rebuild its instructions and tools with it) | `"start"` |
213
+ | `revert` | the conversation was rewound to an earlier point | `"system"` |
214
+ | `refusal` | a refused exchange was left out of history | `"system"` |
215
+ | `model_switch` | the model changed | `"start"` |
216
+ | `settings_change` | a request parameter changed on purpose, e.g. reasoning effort or thinking at the user's request | `"start"` |
217
+ | any other value | | `"start"` |
218
+
219
+ The older kinds keep working: a `compaction` hint declares `{"reason": "compaction", "after": "start"}` and a `model_switch` hint declares `{"reason": "model_switch", "after": "start"}`.
220
+
221
+ **Reach.** A declaration applies to the call that carries it, and to nothing else:
222
+
223
+ - It excuses that call's miss only when the first change, as section 8 finds it between this call and the previous one in its lane, starts at or after the part `after` keeps. The start of a model change is the first block; of a parameter change, the first block of the part section 8.1 says it invalidates; otherwise the first block that differs. A `revert` (after `"system"`) that also changed the tool list is not excused.
224
+ - It does not excuse a miss with the prefix intact (an expiry or a provider-side miss): the break did not cause it. Nor does it excuse a call that read nothing and was sent later than the cache lifetime after the previous call: the cache had expired whatever the harness did, so the miss is an expiry (section 8), with the declared break named beside it. This holds for usage-only records too.
225
+ - It does not reach the next call. A second miss right after a declared break is compared with the call that carried the declaration, and is a miss.
226
+ - When either of the two records is usage-only, where the prefix changed cannot be checked; the declaration is taken at its word and the report says it was not checked.
227
+
228
+ **What a reader does with it.** An excused miss is still a miss of the cache: its status, lost tokens and cost are reported as for any other call. It is reported as an *intentional break* with its declared reason and the change found, and its cost is totalled separately from avoidable misses, so a declaration can move a cost from one total to the other but never hide it. A declaration that does not excuse the miss is reported with the miss, saying why.
229
+
230
+ A malformed `prefix_break` hint (no `reason`, or an invalid `after`) MUST NOT excuse anything; prefixlens drops it with a warning. This is also what a reader older than a form of `after` does with it (`{"system": n}` was added in 1.3): the miss is reported as one, never excused by a position the reader does not know.
231
+
232
+ The same rules decide `assertPrefixStable`'s `allowBreak` option in `prefixlens/test`: `allowBreak: "revert"` allows exactly what a `{"kind": "prefix_break", "reason": "revert"}` hint excuses, and `allowBreak: { after: { system: 1 }, reason: "working memory" }` what the same `after` on a hint does. An `after` there that is not one of the forms above is an error, not a break that allows nothing.
233
+
234
+ ## 7. Lanes and comparison
235
+
236
+ Each call is compared with the previous call in the same lane, where a lane is identified by (`session`, `lane`). Calls that do not build on each other's prefix, such as concurrent subagents, MUST be put in different lanes, or they will be compared with each other. The first call in a lane has no previous call to be compared with, so it cannot lose cached tokens. It is a cold start when it read nothing from the cache. When it did read from the cache, something outside the lane had left the same prefix there (an earlier session with the same tools and instructions, for example): that is a warm start, and it is reported as a hit.
237
+
238
+ ## 8. How prefixlens analyzes a trace (informative)
239
+
240
+ For a call `c` with previous call `p` in the same lane:
241
+
242
+ - `prompt(x) = input_tokens + cache_read_tokens + (cache_write_tokens ?? 0)`.
243
+ - **Hit rate** of `c` = `cache_read_tokens / prompt(c)`. Trace hit rate = Σ reads / Σ prompts.
244
+ - **Expected cached tokens**: what `p` left in the cache. With explicit caching (provider `anthropic`; `openai` when `p.params.prompt_cache_options.mode` is `"explicit"`, which caches only up to the breakpoints a request sets and nothing without one; or a provider other than `openai` and `gemini` whose `p.cache_write_tokens` is not null): `p.cache_read_tokens + p.cache_write_tokens`. With implicit caching (`openai`, `gemini`, or any provider with `p.cache_write_tokens` null): `prompt(p)` rounded down to a multiple of the cache step if it is at least the provider's minimum cacheable size, else 0; or `p.cache_read_tokens + p.cache_write_tokens` if that is larger. The **cache step** is learnt from the trace, per `provider` and `model`: the greatest common divisor of the non-zero `cache_read_tokens` of that provider's and model's implicit-caching records, never below 128 tokens (the step OpenAI caches in), and 128 when the trace has fewer than four such reads or they all have the same value. A gateway in front of a provider can read in other steps than the provider does (1,088 tokens was seen on opencode's free-model gateway, Chat Completions, in November 2026), and a call that exactly extends the previous one then reads less than a 128-step rule expects with nothing wrong; one odd read brings the divisor, and so the step, back down, so a learnt step never hides more than the reads in the trace support. An implicit-caching provider's write figure can raise the expectation but never lower it: a reported zero does not mean the uncached part of `p` was left out of the cache. The minimum cacheable size (default 1024 tokens) and the default TTL (300 seconds) are set per provider in the pricing table's `providers` section. Capped at `prompt(c)`.
245
+ - **Lost tokens** = `max(0, expected − c.cache_read_tokens)`. Because expected is capped at `prompt(c)`, a call whose prompt is shorter than the cache before it (after a compaction) loses at most its own prompt: it cannot pay full price for more tokens than it sent, and this is what the miss cost is counted on. For a `compaction` cause prefixlens also gives the uncapped figure, the size of the cache that was given up, as `abandoned_cached_tokens` in the cause's detail.
246
+ - **Status**: for the first call in a lane, `cold` when it read nothing from the cache and `hit` (a warm start, section 7) when it read some; for every other call, `uncached` (expected below the minimum cacheable size and nothing read); `hit` (lost ≤ tolerance, default 128 tokens; or, with implicit caching and a learnt cache step above 128, lost less than one step on a call whose two full requests show it exactly extends the previous one: same model and cache-relevant params, every block of `p` unchanged and in place); `miss` (read ≤ tolerance); otherwise `partial`. There is no wider blanket tolerance: a shortfall of a whole step, or any shortfall above the tolerance on a call whose prefix changed, is a miss.
247
+ - **Intentional breaks**: a miss or partial miss excused by a declaration (section 6.1) is reported as an intentional break, counted and costed apart from misses. The **miss** count and miss cost of a trace cover only the others.
248
+ - **Cost** = Σ tokens × price from a user-editable pricing table (per million tokens, with separate write prices for the default lifetime, for Anthropic's 1-hour writes and for OpenAI's 12-hour writes). No price is built into the code.
249
+ - **Miss cost** = lost tokens × (the average price this call paid per uncached input or cache-write token − the cache-read price).
250
+ - **Cause** of a miss or partial miss, when both records are full-request: the first of these that applies:
251
+ 0. a call that read nothing, sent later than the TTL after the previous call (item 5), with the model unchanged: the cache expired. Such a call would have missed with the prefix untouched, so a change that items 2 to 4 find as well is not the cause; it is named in the cause's summary and reported as the call's `prefix_change`. A call that read part of the cache shows the cache was still there, so for a partial miss the items below apply as usual;
252
+ 1. model changed;
253
+ 2. the first differing block is a tool (tools added or removed, same tools reordered, or a definition edited) or a system part (edited; or only a short span changed that looks like a timestamp, a date, a relative date such as "today" or "2 hours ago", or an identifier);
254
+ 3. a cache-relevant param changed, by the rules of section 8.1 for the record's `provider`;
255
+ 4. the first differing block is a message: history truncated, compacted, rewound, the oldest messages removed (a sliding window), a message removed, inserted, reordered, merged with its neighbour or split, a tool output rewritten (truncated or expanded), reasoning blocks changed, a dynamic value updated, or the message otherwise edited. Two of these are told apart by what is in front: when the next request's messages are the previous request's with its k oldest removed (k ≥ 1), everything after them unchanged and in order and anything new only after that, the cause is `oldest_messages_removed`, with the count; when new messages come first, fewer than the old ones they replace, followed by the rest of the old history unchanged and in order (however much of it survives), or when most of the history is replaced by something shorter, it is a `compaction`. A `compaction` hint on the record names a compaction whatever the shape. A message that kept every part it was sent with and gained new parts ahead of one of them is reported as `message_inserted`: a message inserted into history reads this way once an SDK or the provider has merged it with the message after it (consecutive user messages are sent as one); new parts after the old ones are an edit that appended;
256
+ 5. nothing changed, or, with explicit caching, the first change comes after the last block of `p` marked `breakpoint` (the part `p` cached is intact): cache expired if the start-to-start gap exceeds the TTL (`p.cache_ttl_seconds`, else the provider default), otherwise a provider-side miss, which does not blame the harness. A request sent within a few seconds of the call that wrote the cache can miss this way: the new entry is not always readable yet. When either request has an `unknown` block (section 4.1), "nothing changed" is not proven, since that block compares equal whatever it held: the cause is then still reported as provider-side, but as *inferred* rather than confirmed, and worded as a provider-side miss or a change in the block the trace does not record.
257
+
258
+ ### 8.1 Which request parameters are part of the cached prefix
259
+
260
+ A parameter is classified by its top-level request key, per provider. *Verified* means measured against the live API; *documented* means the provider's prompt-caching documentation says so; *assumed* means neither, with the reasoning given. A parameter not in the table is assumed cache-relevant from the start of the request, so that a change is never silently ignored; `assertPrefixStable` takes `ignoreParams` for one you have shown is not.
261
+
262
+ | provider | parameter | in the cached prefix? | a change invalidates | evidence |
263
+ |---|---|---|---|---|
264
+ | all | `max_tokens`, `max_output_tokens`, `max_completion_tokens`, `temperature`, `top_p`, `top_k`, `stop`, `stop_sequences`, `n`, `seed`, `logprobs`, `top_logprobs`, `metadata` | no | | assumed: sampling and output limits apply after the prompt is read, and no provider lists them as affecting the cache. `user` is in this row for every provider except OpenAI |
265
+ | anthropic | `tool_choice` | yes | messages only | documented ("What invalidates the cache": changes to `tool_choice` only affect message blocks) |
266
+ | anthropic | `thinking` | yes | everything (messages always; tools and system on models that render it first) | documented |
267
+ | anthropic | `output_config` (`effort`) | yes | everything, as `thinking` | documented for `effort`; assumed for the rest of `output_config` |
268
+ | anthropic | `speed` | yes | system and messages | documented |
269
+ | anthropic | `context_management`, `mcp_servers` | yes | everything | assumed: they change what the model reads (server-side context edits, extra tools) |
270
+ | anthropic | `service_tier` | no | | assumed: billing and capacity only |
271
+ | openai | `tool_choice` | **no** | | **verified on the Responses API**: a warm 5,159-token prefix read 4,992 cached tokens with `"auto"`, again with `"none"` and the tool list unchanged, and again after switching back. Assumed the same on Chat Completions, consistent with OpenAI's advice to set `tool_choice: "none"` rather than remove tools |
272
+ | openai | `parallel_tool_calls`, `reasoning` (`effort`), `text` (`verbosity`, `format`), `context_management` | yes | everything (they change hidden instructions ahead of the prompt) | documented ("Which settings affect the cached prefix?") |
273
+ | openai | `reasoning_effort`, `verbosity`, `response_format` | yes | everything | assumed: the Chat Completions names of the documented Responses settings |
274
+ | openai | `prompt_cache_key` | yes | everything | documented: keys route requests to a cache |
275
+ | openai | `prompt_cache_options`, `prompt_cache_retention` | no | | assumed: they choose which breakpoints are written (`mode`), their minimum lifetime (`ttl`), diagnostics (`comparison_response_id`, new on every call) and a maximum retention; a read still needs the rendered prefix to match. The mode does change what can be read: in explicit-only mode a request reads only at boundaries it marks itself (OpenAI checks "the first 2 and latest 50 explicit breakpoints" of the request), so a call that drops the previous call's breakpoint misses with the prefix intact; prefixlens reports that as a provider-side miss, as it does for Anthropic breakpoints beyond the lookback window |
276
+ | openai | `user` | yes | everything | documented: the API reference says `user` is used to bucket similar requests for cache hits, and deprecates it in favour of `prompt_cache_key` |
277
+ | openai | `store`, `include`, `service_tier`, `safety_identifier`, `background` | no | | assumed: storage, response fields, billing or delivery only |
278
+ | gemini | everything but the common rows (`generationConfig`, `toolConfig`, `cachedContent`, ...) | yes | everything | assumed |
279
+
280
+ **Identifying fields.** `metadata`, `user`, `safety_identifier` and `client_metadata` identify a person, account, device or installation and are not model input; writers SHOULD leave them out of `params` (section 2). When one of them is absent from either of two records, a reader MUST NOT report it as changed: absent means not recorded, not removed. Of these, only OpenAI's `user` is a cache-routing key, so a trace written without it cannot show that a change of `user` caused a miss; such a miss reads as one with the prefix intact. A writer that needs it keeps the field (prefixlens: `keepIdentifiers`, `--keep-identifiers`).
281
+
282
+ Classifications are by provider, not by API: OpenAI's Chat Completions and Responses APIs use different names for most settings, and where they share one (`tool_choice`), the Responses measurement is applied to both, as stated. A provider not listed (a gateway id) gets the common rows and the default.
283
+
284
+ ## 9. Example
285
+
286
+ Three calls in one lane. The second extends the first; the third adds a tool, so the cache from the second is lost. Content of repeated blocks is omitted after its first appearance.
287
+
288
+ ```jsonl
289
+ {"v":1,"ts":"2026-01-01T10:00:00.000Z","provider":"anthropic","model":"claude-opus-5-5","fidelity":"full-request","session":"s1","lane":"main","params":{"max_tokens":32000},"cache_ttl_seconds":300,"request":{"blocks":[{"kind":"tool","key":"read_file","hash":"30e0dcd015ebdc47cd26068d185bf8c2fa77fa79248383ceabec55c715551030","content":{"name":"read_file","description":"Read a file.","input_schema":{"type":"object"}}},{"kind":"system","hash":"fee3c7ab8de0808c86ac65af7fb2c71887f6b55eda5c4e8794a58a4c1f0e9822","content":{"type":"text","text":"You are a coding agent."},"breakpoint":true},{"kind":"message","key":"user","hash":"913f6ca8015045bfd57dd7baa26a020b5b82096e3fe980fbda697495d4507585","content":{"role":"user","content":[{"type":"text","text":"Fix the bug."}]},"breakpoint":true}]},"usage":{"input_tokens":3,"cache_read_tokens":0,"cache_write_tokens":2100,"output_tokens":120}}
290
+ {"v":1,"ts":"2026-01-01T10:00:09.000Z","provider":"anthropic","model":"claude-opus-5-5","fidelity":"full-request","session":"s1","lane":"main","params":{"max_tokens":32000},"cache_ttl_seconds":300,"request":{"blocks":[{"kind":"tool","key":"read_file","hash":"30e0dcd015ebdc47cd26068d185bf8c2fa77fa79248383ceabec55c715551030"},{"kind":"system","hash":"fee3c7ab8de0808c86ac65af7fb2c71887f6b55eda5c4e8794a58a4c1f0e9822","breakpoint":true},{"kind":"message","key":"user","hash":"913f6ca8015045bfd57dd7baa26a020b5b82096e3fe980fbda697495d4507585"},{"kind":"message","key":"assistant","hash":"2359ae584ca07720bc4364a8f6130313f9c48622a57e957db74867071e87157e","content":{"role":"assistant","content":[{"type":"tool_use","id":"t1","name":"read_file","input":{"path":"a.py"}}]}},{"kind":"message","key":"user","hash":"fd50c03bc418abdadc0b0e89fb640e4bf86d01f1eb465d2041903911afd053ef","content":{"role":"user","content":[{"type":"tool_result","tool_use_id":"t1","content":"print(1)"}]},"breakpoint":true}]},"usage":{"input_tokens":3,"cache_read_tokens":2100,"cache_write_tokens":160,"output_tokens":80}}
291
+ {"v":1,"ts":"2026-01-01T10:00:20.000Z","provider":"anthropic","model":"claude-opus-5-5","fidelity":"full-request","session":"s1","lane":"main","params":{"max_tokens":32000},"cache_ttl_seconds":300,"request":{"blocks":[{"kind":"tool","key":"read_file","hash":"30e0dcd015ebdc47cd26068d185bf8c2fa77fa79248383ceabec55c715551030"},{"kind":"tool","key":"web_fetch","hash":"d19924e6b34eb7bd1fdb88375d0fb37824280385b21a9b7119e6a6c99ff08c87","content":{"name":"web_fetch","description":"Fetch a URL.","input_schema":{"type":"object"}}},{"kind":"system","hash":"fee3c7ab8de0808c86ac65af7fb2c71887f6b55eda5c4e8794a58a4c1f0e9822","breakpoint":true},{"kind":"message","key":"user","hash":"913f6ca8015045bfd57dd7baa26a020b5b82096e3fe980fbda697495d4507585"},{"kind":"message","key":"assistant","hash":"2359ae584ca07720bc4364a8f6130313f9c48622a57e957db74867071e87157e"},{"kind":"message","key":"user","hash":"fd50c03bc418abdadc0b0e89fb640e4bf86d01f1eb465d2041903911afd053ef"},{"kind":"message","key":"assistant","hash":"d0358957456d5970f9f8b9c2a82404c0b9dd6b2381b9941dac19d6b706fe40cc","content":{"role":"assistant","content":[{"type":"text","text":"Fixed."}]}},{"kind":"message","key":"user","hash":"8ce9c6a2aaf41c70bb9a882db326a43a050ec7274e358130c2e13a6660f2aa0d","content":{"role":"user","content":[{"type":"text","text":"Thanks."}]},"breakpoint":true}]},"usage":{"input_tokens":3,"cache_read_tokens":0,"cache_write_tokens":2500,"output_tokens":20}}
292
+ ```
293
+
294
+ The hashes are the real SHA-256 of each block's content, so the example can be saved as a file and read by `prefixlens report` as is. prefixlens reports the third call as `turn 3: miss, tool list changed (+1 tool: 1 → 2)`.
295
+
296
+ A usage-only record needs only the required fields:
297
+
298
+ ```json
299
+ {"v":1,"ts":"2026-01-01T10:00:20.000Z","provider":"openai","model":"gpt-4.1","fidelity":"usage-only","lane":"main","usage":{"input_tokens":480,"cache_read_tokens":2048,"cache_write_tokens":null,"output_tokens":95}}
300
+ ```
301
+
302
+ ## 10. Checklist for harnesses
303
+
304
+ 1. Write one line per model call, after the response, with `ts` set to when the request was sent.
305
+ 2. Build blocks from the exact request body you sent, after all your own transformations, in the order of section 4.2.
306
+ 3. Strip `cache_control` (section 4.3), set `breakpoint` where it was, and normalize string message bodies to text parts.
307
+ 4. Hash with canonical JSON and SHA-256; check your implementation against the test vectors.
308
+ 5. Write each block's content once per file and hash-only afterwards, or hash-only throughout if you must redact. For long sessions, also set `request.reuse` (section 4.6) instead of repeating the unchanged prefix.
309
+ 6. Fill `usage` from the final usage of the response (section 3), with `cache_write_tokens: null` for implicit-caching providers.
310
+ 7. Give concurrent or independent conversations (subagents) their own `lane`.
311
+ 8. When you break your own prefix on purpose (compaction, revert, refused exchange left out, model or setting changed at the user's request), add a `prefix_break` hint with its `reason` to the next call (section 6.1). Do not declare anything else: a declaration excuses only the call it is on, and only a change where its reason allows.
312
+ 9. Never write credentials. If a header routes your requests to a cache (`session-id`), record it in `headers`.
@@ -0,0 +1,2 @@
1
+ import type { ImportOptions, ImportResult } from "./index.js";
2
+ export declare function importClaudeCode(input: string, options: ImportOptions): Promise<ImportResult>;