@agentguard-run/burn 0.2.3 → 0.2.6

package/docs/USAGE_AND_PRICING.md

@@ -0,0 +1,132 @@
+# Understand local usage
+
+Burn reads the usage metadata already saved by your coding agent. It separates fresh input, cache writes, cache reads and output. The dollar estimate is the equivalent cost at the recorded API list rates. It is not a subscription bill, an account allowance or a conversion from tokens into your plan's limits.
+
+The observer and reports run locally without network requests. Reports contain usage counts, model identifiers, timestamps and explanations supported by metadata. They do not copy prompt text, file contents, tool arguments or model output into the usage report.
+
+## Commands
+
+```sh
+agentguard-burn why
+agentguard-burn why SESSION_ID json
+agentguard-burn rewrites all
+agentguard-burn pace SESSION_ID
+agentguard-burn statusline SESSION_ID
+agentguard-burn pricing
+```
+
+`why` breaks down a session's recorded usage. `rewrites` lists large prefix writes and the evidence available for their causes. `pace` and `statusline` show a short local summary. The optional final `json` argument on `why` and `rewrites` makes the report suitable for another local program.
+
+## Attribution method in 0.2.5
+
+The first distinct assistant response establishes its session's fixed-prefix baseline from input, cache creation and cache read tokens. The instruction stack + system row uses that initial measured context and the corresponding prefix portion of later cache reads. This baseline includes the initial user message. A rewrite classified as prefix change resets it to that response's context, which can include existing history. The label is a baseline attribution rule, not a claim that instruction files alone contain that many tokens.
+
+History re-sent is each response's cache reads above the fixed prefix, floored at zero. The arriving increment is fresh input plus cache creation after subtracting the previous response's output. Intervening user messages receive conversation tokens. Tool results receive tool output tokens, except a recorded Read result for a previously read path receives re-read file tokens. When several results or user messages share an increment, their recorded UTF-8 byte sizes determine proportions of the measured token total. Integer rounding uses largest remainders so no token disappears. Mixed user and tool intervals are marked shared and counted in the footer.
+
+A qualifying full-prefix rewrite retains its measured cache-creation tokens and is excluded from event-increment attribution. Explicit child transcripts retain their existing fan-out attribution after rewrites. Generated output is counted once. To conserve all recorded usage, the input tokens reserved by previous-output subtraction remain in the unattributed residual, together with intervals without usable event evidence. A single event category can own an increment even when its payload is empty; mixed empty payloads have no measurable byte proportions and remain residual.
+
+Repeated usage snapshots for one provider response keep the original interval rather than consuming later events again. Read paths, tool IDs and event identities are hashed in local state. Only byte counts and metadata survive parsing, never text. Shell commands that happen to read a file remain tool output unless the host records a Read call. Existing explicit host token-category instrumentation takes precedence where available.
+
+The table's Method footer has one sentence per bucket. Zero now means a computed zero rather than a missing measurement. Old pace caches without interval metadata are rebuilt once from the local transcript. When auditing a date range, establish baselines from complete session histories before selecting the responses in that range.
+
+## Cache writes and long sessions
+
+For Claude, `cache_creation_input_tokens` is the total written. When the transcript also includes `cache_creation.ephemeral_5m_input_tokens` and `cache_creation.ephemeral_1h_input_tokens`, Burn uses that split. If the lifetime is unavailable, Burn returns a range between the two published write rates. A long pause alone does not establish the requested cache lifetime. See the [provider's cache usage fields](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration).
+
+A large rewrite after a recorded compaction, a first subagent turn, a recorded prefix change or an idle interval can explain expensive turns. These are evidence labels, not proof that one cause was solely responsible. When metadata does not identify a cause or lifetime, the report says so.
+
+For `claude-fable-5-1`, 500,000 cache-read tokens have a $0.125 API equivalent. Writing that many tokens costs $6.25 with a five-minute lifetime or $10 with a one-hour lifetime. At the same verified cache-read rate, 1.69 billion reads cost $422.50. Multiplying all token categories by the fresh-input rate would give the wrong result.
+
+## Pricing sources and overrides
+
+Every bundled row includes its exact model identifier, `sourceUrl` and `verifiedAt`. The rates were checked on 2026-09-17. The runtime never downloads pricing. Run `agentguard-burn pricing` to inspect the installed table.
+
+The Claude rows use the [official model price list](https://platform.claude.com/docs/en/about-claude/pricing). Amounts below are USD per million tokens in the order fresh input, cache read, five-minute write, one-hour write, output:
+
+* `claude-fable-5-1`: 10, 0.25, 12.5, 20, 50.
+* `claude-fable-5`: 10, 1, 12.5, 20, 50.
+* `claude-opus-5` and `claude-opus-4-8`: 5, 0.5, 6.25, 10, 25.
+* `claude-sonnet-5`: 2, 0.2, 2.5, 4, 10.
+* `claude-haiku-4-5-20251001`: 1, 0.1, 1.25, 2, 5.
+
+The [OpenAI API price list](https://developers.openai.com/api/docs/pricing) supplies these standard rates in the order fresh input, cache read, cache write, output:
+
+* `gpt-6-astra`: 10, 1, 12.5, 50.
+* `gpt-5.6-sol`: 4, 0.4, 5, 20. These are the published promotional rates on the verification date.
+* `gpt-5.6-luna`: 0.2, 0.02, 0.25, 1.2.
+
+These OpenAI rows have one published cache-write price rather than separate lifetime prices. For requests with more than 272,000 input tokens, Burn applies the documented API multiplier of two to fresh input, reads and writes, and 1.5 to output. It uses the request's reported input counts, not the model's advertised context capacity.
+
+The [GPT-5.4 Mini model page](https://developers.openai.com/api/docs/models/gpt-5.4-mini) supplies 0.75 input, 0.075 cached input and 4.5 output. Its separate cache-write rate is unverified and remains `null`. Unknown model identifiers, including unlisted aliases, keep their token counts but have no dollar estimate. Burn does not infer prices from a model family name.
+
+**Codex charges can differ from the API equivalent.** OpenAI's [Enterprise rate card](https://help.openai.com/en/articles/20001415) says that Codex does not charge for cache writes and that Astra in Codex does not incur the API long-context surcharge. Its other billing rules and included subscription allowances also differ. Burn's default table intentionally describes API list prices, not what a Codex subscriber owes. Fast processing, regional premiums, batch discounts, tools, taxes and negotiated rates are outside this standard estimate.
+
+To use different rates, create a local JSON file and set `AGENTGUARD_BURN_PRICING_FILE` to its path. You can also set `insights.pricingFile` in the Burn policy. Otherwise Burn checks `burn-pricing.json` under `AGENTGUARD_HOME`, or the normal Burn home when that variable is absent. Listed models replace the matching bundled row; other bundled rows remain available.
+
+```json
+{
+  "models": {
+    "example-model": {
+      "input": 2,
+      "cacheRead": 0.2,
+      "cacheWrite5m": null,
+      "cacheWrite1h": null,
+      "output": 8,
+      "sourceUrl": "https://example.com/your-agreed-rates",
+      "verifiedAt": "2026-09-17"
+    }
+  }
+}
+```
+
+These example prices are placeholders. Use a source that establishes your actual rates. Every category must be a nonnegative number or `null`; `null` means unknown, and zero means a verified zero price. If a turn has tokens in an unknown category, its full dollar estimate remains unavailable. Partial known categories remain visible in the pricing result.
+
+For a single write rate, set equal `cacheWrite5m` and `cacheWrite1h` values and add `"cacheWriteTtl": "not_tiered"`. An optional `longContext` object takes `aboveInputTokens`, `inputMultiplier` and `outputMultiplier`. An override without that object has no automatic context surcharge. This lets an operator express a verified contract without inheriting an incompatible API rule.
+
+## What the hosts expose
+
+Claude Code supplies `session_id` and `transcript_path` to hooks. Its transcript is written asynchronously, so a hook may observe usage a little after the corresponding response. The hook schema does not promise account rate-limit percentages. See [Claude Code hook input](https://code.claude.com/docs/en/hooks#common-input-fields).
+
+The [Claude Code statusline contract](https://code.claude.com/docs/en/statusline) separately exposes `rate_limits.five_hour.used_percentage`, `rate_limits.seven_day.used_percentage` and each window's `resets_at` in Unix seconds. A window may be absent, and expired windows are removed. `context_window.used_percentage` measures current context occupancy; it is not an account-limit percentage. A custom statusline can invoke Burn with the JSON supplied on stdin:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "agentguard-burn statusline"
+  }
+}
+```
+
+This is an example for operator review. Running the reporting commands does not install this setting. If another statusline is already configured, combine its output with Burn in your existing script instead of replacing it.
+
+In Codex 0.154.0, transcript `token_count` records can contain `rate_limits.primary` and `rate_limits.secondary`. Each window uses `used_percent`, optional `window_minutes` and optional `resets_at` in Unix seconds. Primary and secondary names alone do not establish a five-hour or weekly duration. The released [protocol definitions](https://github.com/openai/codex/blob/rust-v0.154.0/codex-rs/protocol/src/protocol.rs#L2318) establish these fields. The hook contract supplies a transcript path, not a separate promise of quota fields.
+
+Codex input totals include cache reads and writes. Burn separates them before pricing fresh input. Reasoning output is already part of total output and is not added again. The released [usage decoder test](https://github.com/openai/codex/blob/rust-v0.154.0/codex-rs/codex-api/src/sse/responses.rs#L898) demonstrates an input total of 100 consisting of 40 reads and 60 writes, plus 10 output tokens that include five reasoning tokens.
+
+Codex 0.154.0 supports a fixed list of built-in footer items, not an external status command. Its [released statusline implementation](https://github.com/openai/codex/blob/rust-v0.154.0/codex-rs/tui/src/bottom_pane/status_line_setup.rs#L56) and [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference#tuistatus_line) document that boundary. Use its native limit indicators and run the one-line Burn companion in a terminal:
+
+```toml
+[tui]
+status_line = ["model", "context-remaining", "five-hour-limit", "weekly-limit"]
+```
+
+```sh
+agentguard-burn statusline SESSION_ID
+```
+
+## Forecast limits without inventing a quota
+
+The last ten minutes of recorded usage establish cached and uncached token pace and a next-hour projection. An account-limit forecast requires multiple explicit percentage observations from the same unexpired host window. It follows the observed change in percentage over time. Neither a token maximum nor a cache discount is inferred from subscription price, context size or API cost.
+
+When snapshots are missing, stale, unchanged, reset or otherwise insufficient, the line reports an unknown limit with a reason. A forecast reflects recent activity only; other sessions or a change in workload can change the result. The host's own usage screen remains the authority for the remaining allowance.
+
+## Unknown inherited history
+
+Some older Codex fork transcripts copy a parent's usage without an authoritative boundary. Burn excludes that inherited history and reports usage unavailable rather than charging the copy again. Reports across sessions identify how many histories were excluded. Those totals are incomplete. Newer transcripts with an explicit inherited-history ordinal or a child-owned thread settings event can separate the copied prefix from new usage.
+
+## Reservation lock recovery
+
+The reservation lock waits up to eight seconds. A process that fails closed because it could not acquire that lock does not contribute to the decision count or the seven-day age required for enforcement eligibility. Other old ledger rows keep their existing interpretation.
+
+Retiring an abandoned lock is serialized before renaming it, so a stale observer cannot temporarily move a live replacement lock. If a process crashes during the retirement claim itself, the conservative result can be continued fail-closed lock waits. A directory without a valid owner record also requires manual recovery: its creator might be paused before publishing ownership, and directory age cannot prove that process is dead. Recovery requires stopping all clients using that Burn home, confirming that every PID recorded in `burn.lock/owner` and `burn.lock/retiring/owner` is dead, moving that abandoned lock directory aside, then restarting the clients. If either owner record is absent or unreadable, keep every client stopped during recovery. Do not remove a lock while any of those clients is running.

package/fixtures/usage-dedup-session/subagents/agent-synthetic-first.jsonl

@@ -0,0 +1,5 @@
+{"type":"fork-context-ref"}
+{"type":"assistant","timestamp":"2026-09-01T00:00:02Z","uuid":"synthetic-root-block-3","message":{"id":"synthetic-response-a","model":"claude-sonnet-5","usage":{"input_tokens":10,"cache_creation_input_tokens":20,"cache_read_input_tokens":100,"output_tokens":9},"content":[]}}
+{"type":"assistant","timestamp":"2026-09-01T00:00:03Z","uuid":"synthetic-root-spawn","message":{"id":"synthetic-response-b","model":"claude-sonnet-5","usage":{"input_tokens":11,"cache_read_input_tokens":130,"output_tokens":2},"content":[{"type":"tool_use","id":"synthetic-spawn-1","name":"Agent","input":{"description":"synthetic task"}}]}}
+{"type":"assistant","timestamp":"2026-09-01T00:00:04Z","uuid":"synthetic-child-block-1","message":{"id":"synthetic-response-c","model":"claude-sonnet-5","usage":{"input_tokens":5,"cache_creation_input_tokens":30,"cache_read_input_tokens":150,"output_tokens":10},"content":[]}}
+{"type":"assistant","timestamp":"2026-09-01T00:00:05Z","uuid":"synthetic-child-block-2","message":{"id":"synthetic-response-c","model":"claude-sonnet-5","usage":{"input_tokens":5,"cache_creation_input_tokens":30,"cache_read_input_tokens":150,"output_tokens":12},"content":[]}}

package/fixtures/usage-dedup-session/subagents/agent-synthetic-second.jsonl

@@ -0,0 +1,4 @@
+{"type":"fork-context-ref"}
+{"type":"assistant","timestamp":"2026-09-01T00:00:02Z","uuid":"synthetic-root-block-3","message":{"id":"synthetic-response-a","model":"claude-sonnet-5","usage":{"input_tokens":10,"cache_creation_input_tokens":20,"cache_read_input_tokens":100,"output_tokens":9},"content":[]}}
+{"type":"assistant","timestamp":"2026-09-01T00:00:05Z","uuid":"synthetic-copy-c","message":{"id":"synthetic-response-c","model":"claude-sonnet-5","usage":{"input_tokens":5,"cache_creation_input_tokens":30,"cache_read_input_tokens":150,"output_tokens":12},"content":[]}}
+{"type":"assistant","timestamp":"2026-09-01T00:00:06Z","uuid":"synthetic-child-d","message":{"id":"synthetic-response-d","model":"claude-sonnet-5","usage":{"input_tokens":2,"cache_read_input_tokens":200,"output_tokens":3},"content":[]}}

package/fixtures/usage-dedup-session.jsonl

@@ -0,0 +1,4 @@
+{"type":"assistant","timestamp":"2026-09-01T00:00:00Z","uuid":"synthetic-root-block-1","message":{"id":"synthetic-response-a","model":"claude-sonnet-5","usage":{"input_tokens":10,"cache_creation_input_tokens":20,"cache_read_input_tokens":100,"output_tokens":5},"content":[]}}
+{"type":"assistant","timestamp":"2026-09-01T00:00:01Z","uuid":"synthetic-root-block-2","message":{"id":"synthetic-response-a","model":"claude-sonnet-5","usage":{"input_tokens":10,"cache_creation_input_tokens":20,"cache_read_input_tokens":100,"output_tokens":5},"content":[]}}
+{"type":"assistant","timestamp":"2026-09-01T00:00:02Z","uuid":"synthetic-root-block-3","message":{"id":"synthetic-response-a","model":"claude-sonnet-5","usage":{"input_tokens":10,"cache_creation_input_tokens":20,"cache_read_input_tokens":100,"output_tokens":9},"content":[]}}
+{"type":"assistant","timestamp":"2026-09-01T00:00:03Z","uuid":"synthetic-root-spawn","message":{"id":"synthetic-response-b","model":"claude-sonnet-5","usage":{"input_tokens":11,"cache_read_input_tokens":130,"output_tokens":2},"content":[{"type":"tool_use","id":"synthetic-spawn-1","name":"Agent","input":{"description":"synthetic task"}}]}}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentguard-run/burn",
-  "version": "0.2.3",
-  "description": "Local runaway-agent circuit breaker for AI coding agents and local model runtimes. One policy across Claude Code, Cursor, Codex, Ollama, vLLM, LM Studio and raw orchestrators: detects fan-out storms and sustained token burn, blocks the next spawn, and proves what happened with content-free signed receipts. Nothing leaves the machine.",
+  "version": "0.2.6",
+  "description": "Local session usage and runaway-agent circuit breaker. Explain tokens, cache rewrites and API list cost, track pace, warn on heavy turns, and gate agent fan-out with signed receipts. Nothing leaves the machine.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",
   "main": "dist/src/index.js",
@@ -37,7 +37,8 @@
     "fixtures",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "docs"
   ],
   "engines": {
     "node": ">=20.0.0"