@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,318 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { agent_role_profile, type AgentProvider } from '#scripts/agent/agent-role-profile'
+import { codex_usage } from './codex-usage'
+import { CONTEXT_CUT_THRESHOLD } from './context-cut-threshold'
+import { cost_corpus } from './cost-corpus'
+import { cost_transcript, type SessionUsage } from './cost-transcript'
+import { cost_usage } from './cost-usage'
+import { cost_verdict, type OverMeasurement } from './cost-verdict'
+import { own_session } from './own-session'
+import { transcript_cwd } from './transcript-cwd'
+
+// `josh cost` — what the next turn of a run will cost, read from the active provider's own session
+// usage (joshuafolkken/kit#962).
+//
+// Since #2016 this is the `--over` hand-off verdict alone. The readerless report scopes
+// (`--session` / `--issue` / `--all` / `--run` / `--json`) and the `--cap` counterfactual were
+// retired because no rule or decision read them — leaving only the entry judgment `fullrun` /
+// `backlogrun` / `halfrun` / `pre-gate-cut` ask, and the `josh time` run-timing report keeps the
+// hand-off aggregates used to compare the shared context-cut threshold.
+
+const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const USAGE = 'Usage: josh cost (--cut | --over <tokens-per-request>) [--path <dir>]'
+// The read-only verdict's third answer, beside `cost_verdict`'s over/under: a session that cannot be
+// priced at all. Kept here rather than in `cost_verdict`, which only ever decides over vs under.
+const UNMEASURABLE_VERDICT = 'unmeasurable'
+
+type CostVerdict = ReturnType<typeof cost_verdict.classify> | typeof UNMEASURABLE_VERDICT
+
+interface Options {
+	over?: number
+	// The target project whose transcripts to read, or absent for this process's own working
+	// directory (joshuafolkken/kit#1987). From the kit checkout, `--path <dir>` reads another
+	// project's cost.
+	path?: string
+}
+
+interface RawValues {
+	cut?: boolean | undefined
+	over?: string | undefined
+	path?: string | undefined
+}
+
+type Environment = Readonly<Record<string, string | undefined>>
+
+interface RunContext {
+	over: number
+	path: string | undefined
+	provider: AgentProvider
+}
+
+// A threshold of 0 is a legitimate limit — "hand off after any request at all" — so it is accepted.
+// Negative is refused: there is no such thing as a negative cost. An empty value is refused too, so
+// `--over=` does not arrive as "hand off after any request" and stop an unattended run after its
+// first child.
+function to_threshold(raw: string | undefined): number | undefined {
+	if (raw === undefined) return undefined
+	if (raw.trim() === '') return undefined
+
+	const parsed = Number(raw)
+
+	return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : undefined
+}
+
+// A flag that was given but did not parse is a refusal, not an absent flag: `--over abc` must not
+// silently become "no threshold".
+function is_unparsed(raw: string | undefined, parsed: number | undefined): boolean {
+	return parsed === undefined && raw !== undefined
+}
+
+function selected_threshold(values: RawValues): number | undefined {
+	if (values.cut === true) return CONTEXT_CUT_THRESHOLD
+
+	return to_threshold(values.over)
+}
+
+function threshold_option(over: number | undefined): Pick<Options, 'over'> {
+	return over === undefined ? {} : { over }
+}
+
+function path_option(path: string | undefined): Pick<Options, 'path'> {
+	return path === undefined ? {} : { path }
+}
+
+// `exactOptionalPropertyTypes` rejects `{ over: undefined }`, so an absent flag contributes no key
+// at all rather than an undefined one.
+function to_options(values: RawValues): Options | undefined {
+	if (values.cut === true && values.over !== undefined) return undefined
+
+	const over = selected_threshold(values)
+
+	if (is_unparsed(values.over, over)) return undefined
+
+	return { ...threshold_option(over), ...path_option(values.path) }
+}
+
+const PARSE_ARGS_OPTIONS = {
+	cut: { type: 'boolean' },
+	over: { type: 'string' },
+	path: { type: 'string' },
+} as const
+
+function parse_options(argv: ReadonlyArray<string>): Options | undefined {
+	try {
+		const { values } = parseArgs({ args: [...argv], options: PARSE_ARGS_OPTIONS, strict: true })
+
+		return to_options(values)
+	} catch {
+		return undefined
+	}
+}
+
+// An empty corpus is reported, never priced at zero. "No transcript was found" and "this run was
+// free" are different answers, and only one of them is ever true. `session_id` names the session the
+// environment pointed at when its transcript is the one absent (joshuafolkken/kit#2403), so the
+// message says "No transcript named <id>" rather than the whole-corpus "No transcripts found". The
+// wording is `cost_transcript`'s, so `josh time` says the same thing about the same directory.
+function report_empty(cwd: string, session_id: string | undefined): number {
+	const searched = cost_transcript.searched_directories(cost_transcript.transcript_directories(cwd))
+
+	for (const line of cost_transcript.missing_message(searched, session_id)) console.error(line)
+
+	return FAILURE_EXIT_CODE
+}
+
+function provider_of(environment: Environment): AgentProvider | undefined {
+	const resolved = agent_role_profile.resolve_provider(environment)
+
+	return resolved.kind === 'provider' ? resolved.provider : undefined
+}
+
+// The own-session measurement, and — when there is none — which of the two "nothing to measure"
+// answers it is (joshuafolkken/kit#2403). `absent`: the environment named a session whose transcript
+// is not in this corpus, reported by that name and never measured as another session's newest file.
+// `empty`: no transcript at all. `measured` still carries a session that exists but billed nothing,
+// which `report_over` reports as "no requests" — a third, distinct answer.
+type OwnMeasurement =
+	| { kind: 'measured'; measurement: OverMeasurement }
+	| { kind: 'absent'; session_id: string }
+	| { kind: 'empty' }
+
+function measurement_of(session: SessionUsage): OverMeasurement {
+	return {
+		billed_input_per_request: session.records.map((record) =>
+			cost_usage.billed_input(record.totals),
+		),
+	}
+}
+
+function anthropic_own(target: string, environment: Environment): OwnMeasurement {
+	const corpus = cost_corpus.load_corpus(target)
+	const selection = own_session.select_own_session(corpus.files, environment)
+	if (selection.kind === 'absent') return { kind: 'absent', session_id: selection.session_id }
+
+	const session = corpus.sessions[selection.index]
+	if (session === undefined) return { kind: 'empty' }
+
+	return { kind: 'measured', measurement: measurement_of(session) }
+}
+
+function anthropic_measurement(
+	target: string,
+	environment: Environment,
+): OverMeasurement | undefined {
+	const own = anthropic_own(target, environment)
+
+	return own.kind === 'measured' ? own.measurement : undefined
+}
+
+function same_openai_project(target: string, cwd: string): boolean {
+	return cost_transcript.session_cwd(target) === cost_transcript.session_cwd(cwd)
+}
+
+function reject_openai_cross_project(context: RunContext, target: string, cwd: string): boolean {
+	if (
+		context.provider !== 'openai' ||
+		context.path === undefined ||
+		same_openai_project(target, cwd)
+	) {
+		return false
+	}
+
+	console.error(
+		'OpenAI --path cannot select a thread from another project; run josh cost in that project.',
+	)
+
+	return true
+}
+
+// The active provider's own-session measurement, read the same way for `--over` and for the
+// read-only `session_verdict` below, so the two never drift on which session they price.
+function measure(
+	target: string,
+	provider: AgentProvider,
+	environment: Environment,
+): OverMeasurement | undefined {
+	return provider === 'openai'
+		? codex_usage.measurement(target, cost_transcript.home_directory(), environment)
+		: anthropic_measurement(target, environment)
+}
+
+// `--over` for the anthropic provider: measured → the verdict; `absent` → the named session's
+// missing message; `empty` → the whole-corpus missing message. A measured session that billed
+// nothing falls to `report_over`'s "no requests", which keeps a 0-request transcript distinct from a
+// transcript that is not there at all (joshuafolkken/kit#2403).
+function run_over_anthropic(own: OwnMeasurement, target: string, limit: number): number {
+	if (own.kind === 'measured') return cost_verdict.report_over(own.measurement, limit)
+
+	return report_empty(target, own.kind === 'absent' ? own.session_id : undefined)
+}
+
+function run_over_codex(target: string, limit: number, environment: Environment): number {
+	const measurement = measure(target, 'openai', environment)
+	if (measurement !== undefined) return cost_verdict.report_over(measurement, limit)
+
+	console.error(`No Codex usage found for the current OpenAI thread under ${target}.`)
+
+	return FAILURE_EXIT_CODE
+}
+
+// `--over`: what the next turn of this session will cost, read from the session's own transcript
+// alone — identified by id, not by mtime (joshuafolkken/kit#2403).
+function run_over(
+	target: string,
+	limit: number,
+	provider: AgentProvider,
+	environment: Environment,
+): number {
+	if (provider === 'anthropic') {
+		return run_over_anthropic(anthropic_own(target, environment), target, limit)
+	}
+
+	return run_over_codex(target, limit, environment)
+}
+
+// A measurement priced against the shared cut threshold, or `unmeasurable` for the empty session a
+// `report_over` would refuse. Split from `session_verdict` so neither carries more than one decision.
+function verdict_of(measurement: OverMeasurement | undefined): CostVerdict {
+	if (measurement === undefined || measurement.billed_input_per_request.length === 0) {
+		return UNMEASURABLE_VERDICT
+	}
+
+	return cost_verdict.classify(measurement, CONTEXT_CUT_THRESHOLD)
+}
+
+// The `--cut` verdict as a value, printing nothing (joshuafolkken/kit#2165). `run:status` bundles
+// this beside the issue state and the carry record, so it needs the token rather than the exit code
+// `run` returns. `unmeasurable` is the read-only counterpart of `report_empty` / the empty-session
+// error: a session with no provider, no transcript of its own, or no request cannot be priced, and
+// saying so is not the same as `under`.
+function session_verdict(
+	cwd: string = process.cwd(),
+	environment: Environment = process.env,
+): CostVerdict {
+	const provider = provider_of(environment)
+	if (provider === undefined) return UNMEASURABLE_VERDICT
+
+	return verdict_of(measure(cwd, provider, environment))
+}
+
+function run_context(
+	argv: ReadonlyArray<string>,
+	environment: Environment,
+): RunContext | undefined {
+	const options = parse_options(argv)
+	if (options?.over === undefined) return undefined
+	const provider = provider_of(environment)
+	if (provider === undefined) return undefined
+
+	return { over: options.over, path: options.path, provider }
+}
+
+// This process's own working directory, kept as-is: from a lane the transcript search covers the
+// lane's own slug alone (joshuafolkken/kit#2236), so pre-rewriting the cwd to the main checkout here
+// would drop the lane's own slug and hide a dispatched child's transcript (joshuafolkken/kit#1749).
+// `time-cli.ts` gives the same reason.
+function run(
+	argv: ReadonlyArray<string>,
+	cwd: string = process.cwd(),
+	environment: Environment = process.env,
+): number {
+	const context = run_context(argv, environment)
+
+	if (context === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	// `--path <dir>` reads the target project instead of the process cwd (joshuafolkken/kit#1987).
+	const target = transcript_cwd.resolve(context.path, cwd)
+	if (reject_openai_cross_project(context, target, cwd)) return FAILURE_EXIT_CODE
+
+	return run_over(target, context.over, context.provider, environment)
+}
+
+function main(argv: ReadonlyArray<string>): void {
+	process.exitCode = run(argv)
+}
+
+const cost_cli = {
+	UNMEASURABLE_VERDICT,
+	USAGE,
+	parse_options,
+	to_threshold,
+	load_corpus: cost_corpus.load_corpus,
+	attributed: cost_corpus.attributed,
+	run,
+	session_verdict,
+	main,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
+
+export type { CostVerdict, Options }
+export { cost_cli }

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

@@ -0,0 +1,278 @@
+import { cost_attribute } from './cost-attribute'
+import { cost_transcript, type SessionFile, type SessionUsage } from './cost-transcript'
+import type { UsageRecord } from './cost-usage'
+
+// The counters a corpus read could not account for, kept beside the sessions it read. Defined here
+// because `accumulate_missing` is the only producer left once the readerless report modules that
+// once rendered it were retired (#2016).
+interface MissingData {
+	no_usage_lines: number
+	malformed_lines: number
+	unreadable_sessions: number
+	// Delegated units whose owning session's issue could not be determined, so their cost is charged
+	// to no issue at all (joshuafolkken/kit#1812). Filled by the attribution, which is the only step
+	// that knows a unit could not follow its parent; zero from a per-session tally.
+	unattributed_sessions: number
+}
+
+// The corpus of a project's session transcripts, and how each request in it attributes to an issue
+// (joshuafolkken/kit#962, joshuafolkken/kit#1812). Split out of `cost-cli.ts` when that file passed
+// its length limit: the CLI parses flags and prints reports, and this is the reading underneath every
+// scope it prints — the same walk `josh time`'s phase costs read through `cost_cli.attributed`.
+
+interface Corpus {
+	sessions: Array<SessionUsage>
+	// Kept beside the sessions so the whole-session scope can re-read its transcript for the two
+	// decompositions (joshuafolkken/kit#1151). Parsed lazily and only for that one file: classifying
+	// the content blocks of all 158 transcripts to print one issue's cost would be work nothing reads.
+	files: Array<SessionFile>
+	missing: MissingData
+}
+
+function accumulate_missing(sessions: ReadonlyArray<SessionUsage>): MissingData {
+	return {
+		no_usage_lines: sessions.reduce((sum, session) => sum + session.no_usage_lines, 0),
+		malformed_lines: sessions.reduce((sum, session) => sum + session.malformed_lines, 0),
+		unreadable_sessions: sessions.filter((session) => !session.is_readable).length,
+		// Filled by the attribution, which is the only step that knows a unit could not follow its
+		// parent; a per-session tally cannot see it, so it is zero here and set for an issue scope below.
+		unattributed_sessions: 0,
+	}
+}
+
+// Every session for this project, newest first. Once the readerless `--session` scope was retired
+// (#2016) no caller narrows the set, so the whole corpus is read.
+function load_corpus(cwd: string): Corpus {
+	const files = cost_transcript.list_sessions_across(cost_transcript.transcript_directories(cwd))
+	const sessions = files.map((file) => cost_transcript.read_session(file))
+
+	return { sessions, files, missing: accumulate_missing(sessions) }
+}
+
+interface AttributedRecord {
+	record: UsageRecord
+	issue: number
+	// The resident baseline of the session this record was read from. Carried per record because a
+	// scope that spans sessions has no single baseline, and the first record of a *filtered* set is
+	// a warm mid-session request rather than a preamble — reading it as one reported an issue as
+	// 86.5% resident against a real session's 27.7%.
+	baseline_tokens: number
+	// The session this record was read from, and whether that session is a delegated unit. The cost
+	// curve is built from the non-delegated (main-line) sessions' records alone, so it needs both to
+	// group an issue's records back by session and drop the units (joshuafolkken/kit#1853).
+	session_id: string
+	is_delegated: boolean
+}
+
+interface SessionMeta {
+	is_delegated: boolean
+	owner: string
+}
+
+// Whether each session is a delegated unit, and which session delegated it. Read from the files
+// rather than the usages because only the discovery knows where a transcript was found — a unit lives
+// at `<parent>/subagents/agent-<id>.jsonl`, and its owner is the half in front of the separator.
+function session_meta(corpus: Corpus): Map<string, SessionMeta> {
+	return new Map(
+		corpus.files.map((file) => [
+			file.session_id,
+			{ is_delegated: file.is_delegated, owner: cost_transcript.owning_session_id(file) },
+		]),
+	)
+}
+
+// Every distinct issue a session's own records attribute to. A delegated unit reads this from the
+// session that delegated it (joshuafolkken/kit#1812): a `fullrun`'s parent names exactly one, so its
+// units follow it; a parent that ran several names them all, and its unattributed unit could belong to
+// any of them.
+function issue_set(records: ReadonlyArray<UsageRecord>): Set<number> {
+	const issues = cost_attribute
+		.group_by_issue(records)
+		.map((group) => group.issue)
+		.filter((issue) => issue !== cost_attribute.UNATTRIBUTED_KEY)
+
+	return new Set(issues)
+}
+
+// The one issue to inherit, or `UNATTRIBUTED_KEY` where the parent named none or more than one — in
+// which case a unit's own-branchless records stay unattributed and the set above says which issues
+// they might have belonged to.
+function sole_of(issues: ReadonlySet<number>): number {
+	if (issues.size !== 1) return cost_attribute.UNATTRIBUTED_KEY
+
+	return [...issues][0] ?? cost_attribute.UNATTRIBUTED_KEY
+}
+
+// Each non-delegated session's issue set, keyed by session id, for its units to read.
+function owner_sets(
+	corpus: Corpus,
+	meta: ReadonlyMap<string, SessionMeta>,
+): Map<string, Set<number>> {
+	const own = corpus.sessions.filter(
+		(session) => meta.get(session.session_id)?.is_delegated !== true,
+	)
+
+	return new Map(own.map((session) => [session.session_id, issue_set(session.records)]))
+}
+
+// A session's records, each tagged with the issue its own branch names — and, for a delegated unit,
+// the parent's sole issue substituted wherever the branch named none (joshuafolkken/kit#1812). A child
+// that committed carries its own `<N>-` branch exactly as a top-level session does, so it attributes
+// by its own records; only a sub-step that never commits — a review, a survey — carries `main`
+// throughout and falls to the inherited issue. `inherited` is `UNATTRIBUTED_KEY` for a non-delegated
+// session, which makes the substitution a no-op and leaves its branch-driven grouping exactly as before.
+function pairs_with_inherited(
+	session: SessionUsage,
+	inherited: number,
+	is_delegated: boolean,
+): Array<AttributedRecord> {
+	return cost_attribute.group_by_issue(session.records).flatMap((group) =>
+		group.records.map((record) => ({
+			record,
+			issue: group.issue === cost_attribute.UNATTRIBUTED_KEY ? inherited : group.issue,
+			baseline_tokens: session.baseline_tokens,
+			session_id: session.session_id,
+			is_delegated,
+		})),
+	)
+}
+
+const NO_ISSUES: ReadonlySet<number> = new Set()
+
+// The issues the session that delegated this unit touched — or an empty set where the unit is not
+// delegated, its parent is not in the corpus, or that parent named no issue. An empty set reads as
+// "could belong to any issue", the honest candidate for a unit its parent gives nothing to place.
+function parent_issues(
+	session: SessionUsage,
+	meta: ReadonlyMap<string, SessionMeta>,
+	owners: ReadonlyMap<string, Set<number>>,
+): ReadonlySet<number> {
+	const entry = meta.get(session.session_id)
+
+	if (entry?.is_delegated !== true) return NO_ISSUES
+
+	return owners.get(entry.owner) ?? NO_ISSUES
+}
+
+interface SessionPairs {
+	pairs: Array<AttributedRecord>
+	// Present for a delegated unit whose cost could not all be attributed: the issues its parent
+	// touched, which an issue scope counts as a floor when the set contains that issue or is empty.
+	unattributed_candidates?: ReadonlySet<number>
+}
+
+function pairs_of_session(
+	session: SessionUsage,
+	meta: ReadonlyMap<string, SessionMeta>,
+	owners: ReadonlyMap<string, Set<number>>,
+): SessionPairs {
+	const is_delegated = meta.get(session.session_id)?.is_delegated === true
+	const candidates = parent_issues(session, meta, owners)
+	const inherited = is_delegated ? sole_of(candidates) : cost_attribute.UNATTRIBUTED_KEY
+	const pairs = pairs_with_inherited(session, inherited, is_delegated)
+	const has_unattributed = pairs.some((pair) => pair.issue === cost_attribute.UNATTRIBUTED_KEY)
+
+	if (!is_delegated || !has_unattributed) return { pairs }
+
+	return { pairs, unattributed_candidates: candidates }
+}
+
+interface CorpusAttribution {
+	pairs: Array<AttributedRecord>
+	// One entry per delegated unit whose cost could not be attributed: the issues its parent touched.
+	unattributed: Array<ReadonlySet<number>>
+}
+
+// Attribution across the whole corpus, delegated units followed to the session that delegated them
+// (joshuafolkken/kit#1812). The fill-forward walk itself is untouched — a unit is tagged with its
+// parent's issue and a non-delegated session keeps `group_by_issue` exactly as before — so
+// `josh cost --issue` and `josh time`'s phase costs, which both read this, stay in step.
+function attribute_corpus(corpus: Corpus): CorpusAttribution {
+	const meta = session_meta(corpus)
+	const owners = owner_sets(corpus, meta)
+	const per_session = corpus.sessions.map((session) => pairs_of_session(session, meta, owners))
+
+	return {
+		pairs: per_session.flatMap((one) => one.pairs),
+		unattributed: per_session.flatMap((one) =>
+			one.unattributed_candidates === undefined ? [] : [one.unattributed_candidates],
+		),
+	}
+}
+
+// How many unattributed units an issue scope must treat as a floor: those whose parent touched that
+// issue, and those whose parent named nothing (so the unit could belong to any issue).
+function floor_for_issue(
+	unattributed: ReadonlyArray<ReadonlySet<number>>,
+	issue_number: number,
+): number {
+	return unattributed.filter((set) => set.size === 0 || set.has(issue_number)).length
+}
+
+// An occurrence carrying an issue beats one that does not. A copy written before the branch existed
+// has nothing to attribute it to, so keeping it would move a real request into `unattributed`.
+function is_better(candidate: AttributedRecord, existing: AttributedRecord): boolean {
+	const { UNATTRIBUTED_KEY } = cost_attribute
+
+	return existing.issue === UNATTRIBUTED_KEY && candidate.issue !== UNATTRIBUTED_KEY
+}
+
+function values_of(best: ReadonlyMap<string, AttributedRecord>): Array<AttributedRecord> {
+	const collected: Array<AttributedRecord> = []
+
+	for (const [, pair] of best) collected.push(pair)
+
+	return collected
+}
+
+// **Dedupe again, across sessions.** Resuming or forking a session copies the earlier lines into a
+// new transcript file, so one billed request appears in several — 152 such request ids in this
+// repository's own transcripts, some in three files. Per-session dedup does not see them, and every
+// scope spanning more than one session would bill those requests twice or three times.
+function dedupe_across_sessions(pairs: ReadonlyArray<AttributedRecord>): Array<AttributedRecord> {
+	const best = new Map<string, AttributedRecord>()
+
+	for (const pair of pairs) {
+		const existing = best.get(pair.record.request_id)
+
+		if (existing === undefined || is_better(pair, existing)) {
+			best.set(pair.record.request_id, pair)
+		}
+	}
+
+	return values_of(best)
+}
+
+function attributed(corpus: Corpus): Array<AttributedRecord> {
+	return dedupe_across_sessions(attribute_corpus(corpus).pairs)
+}
+
+// The in-scope records of each non-delegated (main-line) session, grouped and kept in the order they
+// were read. The curve is built from these: a delegated unit starts from low context, so mixing its
+// records into the positional quartiles breaks the growth curve a hand-off decision reads
+// (joshuafolkken/kit#1853). A single-issue run on one session yields one group; a run resumed in a
+// second session yields two, which the curve then withholds rather than mixing.
+function mainline_records(pairs: ReadonlyArray<AttributedRecord>): Array<Array<UsageRecord>> {
+	const groups = new Map<string, Array<UsageRecord>>()
+
+	for (const pair of pairs) {
+		if (pair.is_delegated) continue
+
+		groups.set(pair.session_id, [...(groups.get(pair.session_id) ?? []), pair.record])
+	}
+
+	return [...groups.values()]
+}
+
+const cost_corpus = {
+	accumulate_missing,
+	load_corpus,
+	attribute_corpus,
+	floor_for_issue,
+	dedupe_across_sessions,
+	attributed,
+	mainline_records,
+}
+
+export type { AttributedRecord, Corpus, MissingData }
+export { cost_corpus }

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

@@ -0,0 +1,32 @@
+// The three figures a cost report prints — a dollar amount, a token count, a percentage share — and
+// the precision each uses. Shared by the run-tree report modules and by `josh time`'s reports, which
+// render the same figures.
+
+const USD_DECIMALS = 4
+const PERCENT_SCALE = 100
+const PERCENT_DECIMALS = 1
+
+function format_usd(usd: number): string {
+	return `$${usd.toFixed(USD_DECIMALS)}`
+}
+
+function format_tokens(count: number): string {
+	return count.toLocaleString('en-US')
+}
+
+function format_share(part: number, whole: number): string {
+	if (whole === 0) return 'n/a'
+
+	return `${((part / whole) * PERCENT_SCALE).toFixed(PERCENT_DECIMALS)}%`
+}
+
+const cost_format = {
+	USD_DECIMALS,
+	PERCENT_SCALE,
+	PERCENT_DECIMALS,
+	format_usd,
+	format_tokens,
+	format_share,
+}
+
+export { cost_format }