@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,287 @@
+import { json_value } from '#scripts/lib/json-value'
+import { time_instant } from '#scripts/time-runtime/time-instant'
+import { z } from 'zod'
+
+// Reading Claude Code's own session transcripts for what a run actually cost
+// (joshuafolkken/kit#962).
+//
+// **One API response is written to the transcript as several lines.** Every content block —
+// thinking, text, each `tool_use` — becomes its own `assistant` line, and all of them carry the
+// *same* `usage` object. Measured on a real session: 20 assistant lines for 8 requests. Summing
+// lines therefore over-reports the cost by roughly 3x, which is why `request_id` is the unit of
+// aggregation here and a line never is.
+
+// Every optional field is `nullish`, not `optional`. The transcript writes an absent value as
+// `null` rather than by omitting the key — `output_tokens_details: null`, `service_tier: null`,
+// `iterations: null` — and a schema that accepts only `undefined` rejects the whole line. Measured
+// against this project's own transcripts: 12 perfectly valid lines were being counted as
+// unparseable, which is the reader silently mislabelling data in exactly the way this command
+// exists to prevent.
+const CACHE_CREATION_SCHEMA = z.object({
+	ephemeral_1h_input_tokens: z.number().nullish(),
+	ephemeral_5m_input_tokens: z.number().nullish(),
+})
+
+const USAGE_SCHEMA = z.object({
+	input_tokens: z.number(),
+	cache_creation_input_tokens: z.number().nullish(),
+	cache_read_input_tokens: z.number().nullish(),
+	output_tokens: z.number(),
+	output_tokens_details: z.object({ thinking_tokens: z.number().nullish() }).nullish(),
+	cache_creation: CACHE_CREATION_SCHEMA.nullish(),
+})
+
+const MESSAGE_SCHEMA = z.object({
+	id: z.string().nullish(),
+	model: z.string().nullish(),
+	usage: USAGE_SCHEMA.nullish(),
+})
+
+const LINE_SCHEMA = z.object({
+	type: z.string(),
+	requestId: z.string().nullish(),
+	uuid: z.string().nullish(),
+	gitBranch: z.string().nullish(),
+	timestamp: z.string().nullish(),
+	message: MESSAGE_SCHEMA.nullish(),
+})
+
+// Claude Code writes its own locally-generated assistant messages — an API-error notice, a queued
+// interruption — with this model id and an all-zero usage block. They were never sent to the API, so
+// counting them would inflate the request count and raise an "unknown model" warning about
+// something that was never priced.
+const SYNTHETIC_MODEL = '<synthetic>'
+
+// The five billed quantities, kept apart because each is priced differently. Splitting the cache
+// write by TTL is not a refinement: a 1-hour write costs 2x base against a 5-minute write's 1.25x,
+// and this project's sessions run on the 1-hour TTL, so folding them together would under-report
+// every run by the larger half.
+interface UsageTotals {
+	input_tokens: number
+	cache_write_5m_tokens: number
+	cache_write_1h_tokens: number
+	cache_read_tokens: number
+	output_tokens: number
+	thinking_tokens: number
+	// Whether the API actually reported a thinking-token count, kept apart from the count itself
+	// because `thinking_tokens: 0` cannot tell "the model did no thinking" from "the field was
+	// absent" (joshuafolkken/kit#1969). A session row prints "not measured" for the second rather
+	// than a confident 0%, so the distinction has to survive `sum_totals`; it is OR-combined, so a
+	// session is measured once any one of its requests carried a count.
+	thinking_measured: boolean
+}
+
+interface UsageRecord {
+	request_id: string
+	model: string
+	branch: string
+	// The request's instant, as epoch milliseconds — `undefined` where no line of the request carried
+	// a readable timestamp (joshuafolkken/kit#1606). On a single line it is that line's timestamp;
+	// after `dedupe` folds the request's several lines into one record it is the *latest* of them,
+	// which is the response-completion instant a cost window is keyed to (joshuafolkken/kit#1899).
+	//
+	// **`undefined` rather than a sentinel, for the reason `time_instant` exists**: a request whose
+	// instant cannot be read belongs in the unattributed bucket, and a `0` would place it at the
+	// epoch — inside whichever phase window happens to open first, which is the confident wrong
+	// answer this field is meant to avoid.
+	at_ms: number | undefined
+	totals: UsageTotals
+}
+
+// What one transcript line turned out to be. `skipped` is the ordinary case — most lines are user
+// turns, attachments and bookkeeping, and counting those as missing data would bury the two kinds
+// that matter.
+type LineOutcome =
+	| { kind: 'record'; record: UsageRecord }
+	| { kind: 'skipped' }
+	| { kind: 'no_usage' }
+	| { kind: 'malformed' }
+
+const EMPTY_TOTALS: UsageTotals = {
+	input_tokens: 0,
+	cache_write_5m_tokens: 0,
+	cache_write_1h_tokens: 0,
+	cache_read_tokens: 0,
+	output_tokens: 0,
+	thinking_tokens: 0,
+	thinking_measured: false,
+}
+
+const UNKNOWN_MODEL = 'unknown'
+const UNKNOWN_BRANCH = ''
+
+type RawUsage = z.infer<typeof USAGE_SCHEMA>
+
+// The TTL split, taken from `cache_creation` when the transcript carries it. Older lines have only
+// the flat `cache_creation_input_tokens`; those are read as 5-minute writes, the cheaper of the two,
+// so an unknown TTL never inflates the estimate.
+interface CacheWrite {
+	write_5m: number
+	write_1h: number
+}
+
+function split_cache_write(usage: RawUsage): CacheWrite {
+	const total = usage.cache_creation_input_tokens ?? 0
+	const detail = usage.cache_creation
+
+	if (!detail) return { write_5m: total, write_1h: 0 }
+
+	const write_1h = detail.ephemeral_1h_input_tokens ?? 0
+
+	return { write_5m: detail.ephemeral_5m_input_tokens ?? total - write_1h, write_1h }
+}
+
+// The thinking-token count and whether it was reported at all. `output_tokens_details` is `null`
+// when the API sent no breakdown and `thinking_tokens` is `null` inside it when the breakdown omits
+// the field; both collapse to `measured: false`, while a real `0` stays measured.
+interface ThinkingUsage {
+	tokens: number
+	measured: boolean
+}
+
+function thinking_usage(usage: RawUsage): ThinkingUsage {
+	const raw = usage.output_tokens_details?.thinking_tokens
+
+	return { tokens: raw ?? 0, measured: raw !== null && raw !== undefined }
+}
+
+function to_totals(usage: RawUsage): UsageTotals {
+	const { write_5m, write_1h } = split_cache_write(usage)
+	const thinking = thinking_usage(usage)
+
+	return {
+		input_tokens: usage.input_tokens,
+		cache_write_5m_tokens: write_5m,
+		cache_write_1h_tokens: write_1h,
+		cache_read_tokens: usage.cache_read_input_tokens ?? 0,
+		output_tokens: usage.output_tokens,
+		thinking_tokens: thinking.tokens,
+		thinking_measured: thinking.measured,
+	}
+}
+
+type ParsedLine = z.infer<typeof LINE_SCHEMA>
+
+// A line with neither id is its own request rather than a duplicate of one, so the fallback has to
+// be unique per line; an empty string would collapse every such line into one.
+// The id the API gave the request, when the line carries one. `message.id` is the response id, so
+// it identifies the same billed request that `requestId` does.
+function declared_id(data: ParsedLine): string | undefined {
+	return data.requestId ?? data.message?.id ?? data.uuid ?? undefined
+}
+
+function request_id_of(data: ParsedLine, usage: RawUsage): string {
+	const fallback = `${data.timestamp ?? ''}-${String(usage.output_tokens)}`
+
+	return declared_id(data) ?? fallback
+}
+
+function to_record(data: ParsedLine, usage: RawUsage): UsageRecord {
+	return {
+		request_id: request_id_of(data, usage),
+		model: data.message?.model ?? UNKNOWN_MODEL,
+		branch: data.gitBranch ?? UNKNOWN_BRANCH,
+		at_ms: time_instant.parse_instant(data.timestamp),
+		totals: to_totals(usage),
+	}
+}
+
+const ASSISTANT_TYPE = 'assistant'
+
+function is_priced_line(data: ParsedLine): boolean {
+	return data.type === ASSISTANT_TYPE && data.message?.model !== SYNTHETIC_MODEL
+}
+
+function classify(data: ParsedLine): LineOutcome {
+	if (!is_priced_line(data)) return { kind: 'skipped' }
+
+	const usage = data.message?.usage
+
+	return usage ? { kind: 'record', record: to_record(data, usage) } : { kind: 'no_usage' }
+}
+
+function parse_line(line: string): LineOutcome {
+	if (line.trim() === '') return { kind: 'skipped' }
+
+	const parsed = LINE_SCHEMA.safeParse(json_value.parse_or_undefined(line))
+
+	return parsed.success ? classify(parsed.data) : { kind: 'malformed' }
+}
+
+// The later of two request instants, treating `undefined` as no reading rather than as an early one:
+// a line that carried no timestamp must not pull a request's instant back to nothing when a sibling
+// line of the same request does carry one (joshuafolkken/kit#1899).
+function later_instant(left: number | undefined, right: number | undefined): number | undefined {
+	if (left === undefined) return right
+	if (right === undefined) return left
+
+	return Math.max(left, right)
+}
+
+// One record per request, in first-seen order. Order matters downstream: issue attribution reads
+// the branch sequence, so a Map (which preserves insertion order) is the right container and a Set
+// of ids plus a filter would be the same thing written twice.
+//
+// **`at_ms` is folded to the request's latest line, not its first (joshuafolkken/kit#1899).** One
+// response is written thinking → text → `tool_use` (see the file header), all sharing one request id,
+// and a round trip's cost window opens at the `tool_use` line — the last of them. Keeping the first
+// line's instant put every tool-issuing request *before* its own window, where it fell to the
+// `no_tool_call` bucket; the latest instant is the response-completion time, which is where the window
+// begins. Every other field stays the first-seen record's, so the branch sequence is untouched.
+function dedupe(records: ReadonlyArray<UsageRecord>): Array<UsageRecord> {
+	const by_id = new Map<string, UsageRecord>()
+
+	for (const record of records) {
+		const seen = by_id.get(record.request_id)
+		const at_ms = later_instant(seen?.at_ms, record.at_ms)
+
+		by_id.set(record.request_id, { ...(seen ?? record), at_ms })
+	}
+
+	return [...by_id.values()]
+}
+
+function add_totals(left: UsageTotals, right: UsageTotals): UsageTotals {
+	return {
+		input_tokens: left.input_tokens + right.input_tokens,
+		cache_write_5m_tokens: left.cache_write_5m_tokens + right.cache_write_5m_tokens,
+		cache_write_1h_tokens: left.cache_write_1h_tokens + right.cache_write_1h_tokens,
+		cache_read_tokens: left.cache_read_tokens + right.cache_read_tokens,
+		output_tokens: left.output_tokens + right.output_tokens,
+		thinking_tokens: left.thinking_tokens + right.thinking_tokens,
+		thinking_measured: left.thinking_measured || right.thinking_measured,
+	}
+}
+
+function sum_totals(records: ReadonlyArray<UsageRecord>): UsageTotals {
+	let total = EMPTY_TOTALS
+
+	for (const record of records) total = add_totals(total, record.totals)
+
+	return total
+}
+
+// Everything the run paid to send, whatever rate each part was billed at. `josh cost --over` reads
+// this per request; `josh time` breaks it into resident preamble and conversation history.
+function billed_input(totals: UsageTotals): number {
+	return (
+		totals.input_tokens +
+		totals.cache_write_5m_tokens +
+		totals.cache_write_1h_tokens +
+		totals.cache_read_tokens
+	)
+}
+
+const cost_usage = {
+	EMPTY_TOTALS,
+	UNKNOWN_MODEL,
+	SYNTHETIC_MODEL,
+	parse_line,
+	dedupe,
+	add_totals,
+	sum_totals,
+	billed_input,
+}
+
+export type { LineOutcome, UsageRecord, UsageTotals }
+export { cost_usage }

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

@@ -0,0 +1,89 @@
+// The `--over` hand-off flag of `josh cost`, kept apart from the CLI wiring because it turns a run
+// into a one-line verdict rather than a table (joshuafolkken/kit#1838). It answers what the next turn
+// of a session will cost, and takes only the figures its verdict needs — an over measurement — never
+// a whole report. The `--cap` counterfactual it once sat beside was retired in #2016 as readerless.
+
+import { RECENT_REQUEST_WINDOW } from './context-cut-threshold'
+
+const FAILURE_EXIT_CODE = 1
+const OVER_VERDICT = 'over'
+const UNDER_VERDICT = 'under'
+
+// What `--over` reads of a session: the billed input each request paid, oldest first. The whole
+// per-request sequence is carried rather than a single sum because the hand-off prices the recent
+// tail alone (joshuafolkken/kit#2295) — a long session's whole-session average lags its current
+// context by dozens of requests, so a sum could not answer what the recent window actually cost.
+interface OverMeasurement {
+	billed_input_per_request: ReadonlyArray<number>
+}
+
+// The most recent requests the hand-off prices, oldest first — the whole sequence when it is shorter
+// than the window, so a session with fewer than `RECENT_REQUEST_WINDOW` requests is priced on what it
+// has rather than padded.
+function recent_requests(measurement: OverMeasurement): ReadonlyArray<number> {
+	return measurement.billed_input_per_request.slice(-RECENT_REQUEST_WINDOW)
+}
+
+// What a turn costs is decided by the accumulated preamble, not by what the turn does, so the
+// marginal cost of a session is the billed input its recent requests paid. Measured across one
+// `epicrun` that ran six children in one context: 222k per request during the first child, 645k
+// during the sixth — the same work at 2.9x the price (joshuafolkken/kit#968).
+//
+// The recent window rather than the whole session, because a long parent's whole-session average
+// lags its current context by dozens of requests (joshuafolkken/kit#2295); the recent average says
+// what the *next* turn will cost, which is the thing a hand-off decision turns on.
+function per_request_cost(measurement: OverMeasurement): number {
+	const window = recent_requests(measurement)
+	if (window.length === 0) return 0
+
+	const total = window.reduce((sum, billed) => sum + billed, 0)
+
+	return Math.round(total / window.length)
+}
+
+// The bare over/under decision, without a report: `run:status` reads this same verdict read-only
+// (joshuafolkken/kit#2165), so the comparison lives here once rather than being copied there. A
+// threshold of exactly `cost` is under, matching the `>` the printed report used.
+function classify(
+	measurement: OverMeasurement,
+	limit: number,
+): typeof OVER_VERDICT | typeof UNDER_VERDICT {
+	return per_request_cost(measurement) > limit ? OVER_VERDICT : UNDER_VERDICT
+}
+
+// The stderr line names the window the average covers, so the reader can tell a recent-tail average
+// from a whole-session one (joshuafolkken/kit#2295): "the last W of T request(s)" reads W when the
+// session is longer than the window and the whole count when it is shorter.
+function over_summary(measurement: OverMeasurement, limit: number): string {
+	const total = measurement.billed_input_per_request.length
+	const window = recent_requests(measurement).length
+
+	return `${String(per_request_cost(measurement))} billed input tokens per request over the last ${String(window)} of ${String(total)} request(s); limit ${String(limit)}`
+}
+
+// A verdict, not a table: the point of the flag is that the hand-off is decided by a number rather
+// than by whether the run feels long, which is a judgement made under exactly the pressure that
+// resolves it the wrong way.
+function report_over(measurement: OverMeasurement | undefined, limit: number): number {
+	if (measurement === undefined || measurement.billed_input_per_request.length === 0) {
+		console.error('No requests in this session; there is nothing to hand off.')
+
+		return FAILURE_EXIT_CODE
+	}
+
+	console.info(classify(measurement, limit))
+	console.error(over_summary(measurement, limit))
+
+	return 0
+}
+
+const cost_verdict = {
+	OVER_VERDICT,
+	UNDER_VERDICT,
+	classify,
+	per_request_cost,
+	report_over,
+}
+
+export type { OverMeasurement }
+export { cost_verdict }

package/scripts/cost-runtime/own-session.ts

@@ -0,0 +1,58 @@
+import { agent_session_environment } from '#scripts/josh/agent-session-environment'
+import { cost_transcript, type SessionFile } from './cost-transcript'
+
+// Which transcript in a listing is the *calling* session's own (joshuafolkken/kit#2403).
+//
+// **The mtime was measuring another session.** `latest_own_index` took the newest non-delegated
+// transcript as "the run that just finished", which is right for a report run after a run ends but
+// wrong for a session asking its *own* cost while another is still writing: a `backlogrun` parent
+// waiting on a lane child stops writing its own transcript, so the child's is always newer, and the
+// parent's `--cut` priced the child — reading 34 real requests as none and cutting a session that
+// was under budget.
+//
+// **Claude Code exports the running session's id, so the session can name its own file** rather than
+// guess by time. When the environment names one, the selection is by id and nothing else — a newer
+// transcript under any other slug is never picked. When it names none (a plain shell outside a
+// session), the mtime fallback is exactly the behavior this replaces.
+
+type Environment = Readonly<Record<string, string | undefined>>
+
+const NOT_FOUND = -1
+
+// The calling session's own transcript in a listing:
+//   - `own` — its index, either the session the environment named or (with no name) the newest own
+//     file `latest_own_index` picks;
+//   - `absent` — the environment named a session whose transcript is not in the listing, which is
+//     measured as "not found" rather than folded to another session's newest file.
+type OwnSessionSelection = { kind: 'own'; index: number } | { kind: 'absent'; session_id: string }
+
+// The running session's id, or `undefined` when the environment names none — an empty value counts as
+// none, so `CLAUDE_CODE_SESSION_ID=` does not read as a session named the empty string.
+function session_id_of(environment: Environment): string | undefined {
+	const value = environment[agent_session_environment.SESSION_ID_KEY]
+
+	return value === undefined || value === '' ? undefined : value
+}
+
+function select_own_session(
+	files: ReadonlyArray<SessionFile>,
+	environment: Environment,
+): OwnSessionSelection {
+	const session_id = session_id_of(environment)
+
+	if (session_id === undefined) {
+		return { kind: 'own', index: cost_transcript.latest_own_index(files) }
+	}
+
+	const index = files.findIndex((file) => file.session_id === session_id)
+
+	return index === NOT_FOUND ? { kind: 'absent', session_id } : { kind: 'own', index }
+}
+
+const own_session = {
+	session_id_of,
+	select_own_session,
+}
+
+export type { OwnSessionSelection }
+export { own_session }

package/scripts/cost-runtime/transcript-cwd.ts

@@ -0,0 +1,14 @@
+import path from 'node:path'
+
+// `--path <dir>` names the target project whose transcripts to read, resolved to an absolute path
+// (joshuafolkken/kit#1987). The transcript slug is derived from the exact cwd string and
+// `~/.claude/projects/<slug>` was written from an absolute one, so a relative `--path` would slugify
+// to a folder that was never written. Shared by `josh cost` and `josh time` so the two resolve a
+// target identically — a second copy of this rule is how one of the two quietly stops finding it.
+function resolve(target: string | undefined, cwd: string): string {
+	return target === undefined ? cwd : path.resolve(target)
+}
+
+const transcript_cwd = { resolve }
+
+export { transcript_cwd }

package/scripts/delegation/delegation-cli.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { delegation_policy } from './delegation-policy'
+
+// `josh delegate <step>` — may this step run in a cheaper execution tier? (joshuafolkken/kit#969)
+//
+// A command rather than a paragraph, for the reason `josh review:level` is one: a rule an agent
+// applies from memory is a rule an agent can talk itself out of, and this is the rule that decides
+// how carefully the next thing is done.
+
+const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const USAGE = 'Usage: josh delegate <step> | josh delegate --list'
+
+function print_list(): number {
+	console.info('delegatable:')
+
+	for (const step of delegation_policy.DELEGATABLE_STEPS) {
+		console.info(`  ${step.name}\n    does     ${step.does}\n    verified ${step.verifier}`)
+	}
+
+	console.info('\nkept (considered and rejected):')
+
+	for (const step of delegation_policy.REJECTED_STEPS) {
+		console.info(`  ${step.name}\n    because  ${step.because}`)
+	}
+
+	console.info('\nAnything not listed above is kept. The list is the whole of it.')
+
+	return 0
+}
+
+const LIST_FLAG = '--list'
+const FLAG_PREFIX = '-'
+
+// Every reading of the argument goes through this one function, because the guard and the branch
+// disagreeing about surrounding whitespace is the defect itself: the guard trimmed and `run` did
+// not, so `josh delegate ' --list'` passed as a known flag and then fell through to a verdict about
+// a step called ` --list` (joshuafolkken/kit#1096). The policy lookup trims too, which is why
+// `josh delegate ' --help'` had already slipped past an untrimmed guard (joshuafolkken/kit#969).
+function normalized(argument: string): string {
+	return argument.trim()
+}
+
+// A step name never starts with a dash, so anything that does is a flag — and the only flag this
+// command has is `--list`. Without this, `josh delegate --help` answered `keep`: a mistyped
+// invocation would read as a verdict about a step called `--help` (joshuafolkken/kit#969).
+function is_unknown_flag(argument: string): boolean {
+	const trimmed = normalized(argument)
+
+	return trimmed.startsWith(FLAG_PREFIX) && trimmed !== LIST_FLAG
+}
+
+// Exactly one argument, non-empty, and either the one flag this command has or a step name.
+function is_refused(argv: ReadonlyArray<string>): boolean {
+	const [first, ...rest] = argv
+
+	if (first === undefined || rest.length > 0) return true
+
+	return normalized(first) === '' || is_unknown_flag(first)
+}
+
+function run(argv: ReadonlyArray<string>): number {
+	if (is_refused(argv)) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const [first = ''] = argv
+	const argument = normalized(first)
+
+	if (argument === LIST_FLAG) return print_list()
+
+	// The verdict alone on stdout so `$(josh delegate <step>)` reads it; the reason on stderr so a
+	// person sees why without a shell having to parse around it.
+	console.info(delegation_policy.verdict_for(argument))
+	console.error(delegation_policy.reason_for(argument))
+
+	return 0
+}
+
+function main(argv: ReadonlyArray<string>): void {
+	process.exitCode = run(argv)
+}
+
+const delegation_cli = { USAGE, print_list, run, main }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
+
+export { delegation_cli }