@joshuafolkken/kit 1.872.0

package/scripts/cost-runtime/cost-pricing.ts

@@ -0,0 +1,176 @@
+import { cost_usage, type UsageTotals } from './cost-usage'
+
+// The current Claude price list, and the three multipliers that make a token's price depend on how
+// it was sent (joshuafolkken/kit#962).
+//
+// A run's cost is not "tokens x one rate". A cache read costs a tenth of base input, a 5-minute
+// cache write 1.25x, a 1-hour cache write 2x, and output 5x. On a measured request with
+// `cache_read_input_tokens` 97,190 against `input_tokens` 2, an estimate that ignored the
+// multipliers would be wrong by more than an order of magnitude in either direction depending on
+// which single rate it picked.
+
+const CACHE_WRITE_5M_MULTIPLIER = 1.25
+const CACHE_WRITE_1H_MULTIPLIER = 2
+const CACHE_READ_MULTIPLIER = 0.1
+const TOKENS_PER_MILLION = 1_000_000
+
+interface ModelPrice {
+	// USD per million tokens.
+	input: number
+	output: number
+}
+
+// Base input/output rates per million tokens. Cache rates are derived from `input` by the
+// multipliers above rather than listed, because they are defined as multiples of it — writing them
+// out would let the two drift.
+/* eslint-disable @typescript-eslint/naming-convention */
+const MODEL_PRICES: Record<string, ModelPrice> = {
+	'claude-fable-5': { input: 10, output: 50 },
+	'claude-mythos-5': { input: 10, output: 50 },
+	'claude-opus-5': { input: 5, output: 25 },
+	'claude-opus-4-8': { input: 5, output: 25 },
+	'claude-opus-4-7': { input: 5, output: 25 },
+	'claude-opus-4-6': { input: 5, output: 25 },
+	'claude-sonnet-5': { input: 2, output: 10 },
+	'claude-sonnet-4-6': { input: 3, output: 15 },
+	'claude-haiku-4-5': { input: 1, output: 5 },
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+const CONTEXT_MARKER = '['
+
+// Claude Code appends a context-window marker to the model id it records — `claude-opus-5[1m]` —
+// and a deployment may carry a date suffix. Both name the same priced model, so the id is reduced
+// to its longest prefix that the table knows rather than reported as unknown.
+//
+// The `[1m]` marker is the 1M-context beta, and stripping it to the base rate is confirmed correct,
+// not an approximation (joshuafolkken/kit#1838). The published price list — platform.claude.com
+// "Long context pricing", read 2026-09 — states that Claude 4.6 and later models "include the full
+// 1M token context window at standard pricing (a 900k-token request is billed at the same per-token
+// rate as a 9k-token request)". Every id in `MODEL_PRICES` is 4.6-or-later, so no request has an
+// input-size surcharge band to account for, whatever its size. (Fast mode is a separate premium, but
+// it is signalled by `speed: "fast"` rather than by the context marker, so it is not this marker's
+// concern.) Were a future model to reintroduce a >200K band, the marker could no longer be stripped
+// blindly and this function would branch on the input size instead.
+function resolve_price(model: string): ModelPrice | undefined {
+	const base = model.split(CONTEXT_MARKER)[0] ?? model
+	const direct = MODEL_PRICES[base]
+
+	if (direct !== undefined) return direct
+
+	const [matched] = Object.keys(MODEL_PRICES)
+		.filter((id) => base.startsWith(id))
+		.toSorted((left, right) => right.length - left.length)
+
+	return matched === undefined ? undefined : MODEL_PRICES[matched]
+}
+
+function estimate_cost(totals: UsageTotals, price: ModelPrice): number {
+	const weighted_input =
+		totals.input_tokens +
+		totals.cache_write_5m_tokens * CACHE_WRITE_5M_MULTIPLIER +
+		totals.cache_write_1h_tokens * CACHE_WRITE_1H_MULTIPLIER +
+		totals.cache_read_tokens * CACHE_READ_MULTIPLIER
+
+	return (weighted_input * price.input + totals.output_tokens * price.output) / TOKENS_PER_MILLION
+}
+
+// The five dollar terms `estimate_cost` sums, kept apart so a report can say what a run's dollars
+// were spent on rather than only their total (joshuafolkken/kit#1912). Each is priced by the same
+// multipliers `estimate_cost` uses — the exported constants above — so the five always sum to
+// `estimate_cost(totals, price)`. It is a decomposition of the same arithmetic, not a second price
+// list, which is why the weights live in the constants both read rather than in either function.
+interface CostComposition {
+	input_usd: number
+	cache_write_5m_usd: number
+	cache_write_1h_usd: number
+	cache_read_usd: number
+	output_usd: number
+}
+
+function priced(tokens: number, rate: number): number {
+	return (tokens * rate) / TOKENS_PER_MILLION
+}
+
+function estimate_composition(totals: UsageTotals, price: ModelPrice): CostComposition {
+	return {
+		input_usd: priced(totals.input_tokens, price.input),
+		cache_write_5m_usd: priced(
+			totals.cache_write_5m_tokens * CACHE_WRITE_5M_MULTIPLIER,
+			price.input,
+		),
+		cache_write_1h_usd: priced(
+			totals.cache_write_1h_tokens * CACHE_WRITE_1H_MULTIPLIER,
+			price.input,
+		),
+		cache_read_usd: priced(totals.cache_read_tokens * CACHE_READ_MULTIPLIER, price.input),
+		output_usd: priced(totals.output_tokens, price.output),
+	}
+}
+
+interface ModelCost {
+	model: string
+	totals: UsageTotals
+	// Absent when the model id is not in the price table. Reported as unknown rather than priced at
+	// zero: a silent zero reads as "this run was free", which is the one answer that is never true.
+	cost_usd?: number
+}
+
+function to_model_cost(model: string, totals: UsageTotals): ModelCost {
+	const price = resolve_price(model)
+
+	if (price === undefined) return { model, totals }
+
+	return { model, totals, cost_usd: estimate_cost(totals, price) }
+}
+
+interface ModelUsage {
+	model: string
+	totals: UsageTotals
+}
+
+// Per-model, because a session routinely mixes tiers — a subagent on Haiku inside an Opus run — and
+// one blended rate would be wrong for both.
+function cost_by_model(records: ReadonlyArray<ModelUsage>): Array<ModelCost> {
+	const grouped = new Map<string, UsageTotals>()
+
+	for (const record of records) {
+		const running = grouped.get(record.model) ?? cost_usage.EMPTY_TOTALS
+
+		grouped.set(record.model, cost_usage.add_totals(running, record.totals))
+	}
+
+	return [...grouped].map(([model, totals]) => to_model_cost(model, totals))
+}
+
+// The priced total, and what could not be priced. Both halves are returned: a caller that showed
+// only the sum would present a partial figure as the whole answer.
+function total_cost(costs: ReadonlyArray<ModelCost>): { usd: number; unpriced: Array<string> } {
+	return {
+		usd: costs.reduce((sum, entry) => sum + (entry.cost_usd ?? 0), 0),
+		unpriced: costs.filter((entry) => entry.cost_usd === undefined).map((entry) => entry.model),
+	}
+}
+
+// The priced total in dollars, discarding the unpriced-model list — the one-line composition of
+// `total_cost` over `cost_by_model` that callers reach for when they need only the number, kept here
+// so it is not spelled out at each call site (joshuafolkken/kit#1939).
+function cost_of(records: ReadonlyArray<ModelUsage>): number {
+	return total_cost(cost_by_model(records)).usd
+}
+
+const cost_pricing = {
+	CACHE_WRITE_5M_MULTIPLIER,
+	CACHE_WRITE_1H_MULTIPLIER,
+	CACHE_READ_MULTIPLIER,
+	MODEL_PRICES,
+	resolve_price,
+	estimate_cost,
+	estimate_composition,
+	cost_by_model,
+	total_cost,
+	cost_of,
+}
+
+export type { CostComposition, ModelCost, ModelPrice, ModelUsage }
+export { cost_pricing }

package/scripts/cost-runtime/cost-tokens.ts

@@ -0,0 +1,84 @@
+// Estimating tokens for the parts of the context the transcript records as text
+// (joshuafolkken/kit#1151).
+//
+// **Why an estimate exists at all.** The transcript reports real token counts for exactly two
+// things: what each request was billed, and how many of a response's output tokens were thinking.
+// Everything else — `CLAUDE.md`, a tool result, a Bash command body — is stored as text with no
+// count beside it, and Claude's tokenizer is not public. So a breakdown of the resident block or of
+// the conversation is an estimate by construction, and the report says so wherever it prints one.
+//
+// **Why two terms rather than one bytes-per-token ratio.** A single ratio is wrong by a factor of
+// three across this project's own content: English markdown runs about 3 characters per token,
+// while Japanese runs about one token per character at 3 bytes each. Splitting on the ASCII
+// boundary removes that error without pretending to be a tokenizer.
+//
+// Both constants were calibrated against this repository's transcripts, using the one place where a
+// real count sits beside real text: an assistant response whose content is only `text` blocks and
+// whose `thinking_tokens` is 0, where `output_tokens` is the token count of exactly that text.
+//
+// - **Wide characters — 1 token each.** A least-squares fit over 238 such responses (197,259 ASCII
+//   and 164,073 wide characters against 257,036 output tokens) put the wide coefficient at 0.991.
+// - **ASCII — 3 characters per token**, taken from the one clean reading in that set: the responses
+//   that are almost entirely ASCII, which give 2.97. The other readings are all *denser* and each is
+//   denser for a reason that does not apply to a document like `CLAUDE.md`. Subtracting the wide
+//   term across the whole set leaves 2.12, but that ASCII is markdown scaffolding embedded in
+//   Japanese — punctuation, bullets, table pipes, identifiers in backticks — which tokenizes far
+//   denser than prose; the same figure rises monotonically as the wide fraction falls (2.08 → 2.27 →
+//   2.97). And the resident baseline moved 309–1,116 tokens across `CLAUDE.md` growth of
+//   807–2,045 bytes, i.e. 1.8–2.6, but other resident surfaces grew in those same commits, so that
+//   reading attributes their tokens to `CLAUDE.md`'s bytes and is biased dense by construction.
+//
+// **The residual error runs in one direction, and the report says where it lands.** If 3 is too
+// generous for some content, the rows sized from repository files are *under*-counted and the
+// difference falls into the harness remainder that absorbs what cannot be sized — which is therefore an upper bound
+// on what the transcript cannot decompose, and the sized rows a lower bound on what it can. That is
+// why the remainder is one named row rather than a figure distributed over the others.
+
+const ASCII_CHARS_PER_TOKEN = 3
+const WIDE_TOKENS_PER_CHAR = 1
+const ASCII_LIMIT = 128
+
+interface CharCounts {
+	ascii_chars: number
+	wide_chars: number
+}
+
+// Iterated by code point rather than by UTF-16 unit, so an emoji or any other astral character
+// counts once instead of twice. `for…of` over a string yields code points.
+function count_chars(text: string): CharCounts {
+	let ascii_chars = 0
+	let wide_chars = 0
+
+	for (const char of text) {
+		if ((char.codePointAt(0) ?? 0) < ASCII_LIMIT) ascii_chars += 1
+		else wide_chars += 1
+	}
+
+	return { ascii_chars, wide_chars }
+}
+
+function estimate(text: string): number {
+	const { ascii_chars, wide_chars } = count_chars(text)
+
+	return Math.round(ascii_chars / ASCII_CHARS_PER_TOKEN) + wide_chars * WIDE_TOKENS_PER_CHAR
+}
+
+// The token image of a byte count, for content that is pure ASCII — where one byte is one character,
+// so this is exactly `estimate` of such a document and rounds the same way. A budget expressed in
+// both units has to agree with itself on ASCII, and this is the conversion that makes the two the
+// same limit rather than two limits to reconcile. Anything denser costs more tokens per byte, so the
+// token limit binds first there, which is the whole reason for holding one.
+function ascii_bytes_to_tokens(bytes: number): number {
+	return Math.round(bytes / ASCII_CHARS_PER_TOKEN)
+}
+
+const cost_tokens = {
+	ASCII_CHARS_PER_TOKEN,
+	WIDE_TOKENS_PER_CHAR,
+	count_chars,
+	estimate,
+	ascii_bytes_to_tokens,
+}
+
+export type { CharCounts }
+export { cost_tokens }