@namzu/sdk 21.0.0 → 22.0.0

package/src/runtime/query/checkpoint.ts

@@ -43,11 +43,32 @@ export function toCheckpointListEntry(cp: IterationCheckpoint): CheckpointListEn
  * the same restore path as any other checkpoint.
  *
  * The projection is lossy: `costInfo`, `guardState.elapsedMs` and
- * `toolResultHashes` are not captured at emergency-save time and default
- * to zero/empty values. The synthetic
+ * `toolResultHashes` are not captured at emergency-save time. The synthetic
  * checkpoint id is derived deterministically from the emergency save id so
  * re-projecting the same dump yields the same {@link CheckpointId}.
  *
+ * ## The cost projection says "unknown", not "zero"
+ *
+ * `costInfo` used to default to `{ ...ZERO_COST }` beside a `tokenUsage` the
+ * dump preserves faithfully — a run that had spent real money coming back as
+ * one that had spent nothing. That is the same lie the price catalogue was
+ * added to end, arriving through the restore path instead of the accumulation
+ * one, and it took `runConfig.costLimitUsd` back to being enforced against a
+ * zero with it.
+ *
+ * It also broke the accumulator downstream. `accumulateCost` decides whether
+ * one rate card describes the whole total by asking whether the total is
+ * FRESH — zero cost, zero unpriced tokens, no rates — and `ZERO_COST` is
+ * exactly that shape. So the first turn after such a resume adopted its own
+ * rate card as covering the pre-crash spend too, and reported a number that
+ * was confidently wrong while looking like a measured one.
+ *
+ * Saying instead that the pre-crash tokens are UNPRICED is the true statement,
+ * in the vocabulary {@link CostInfo} already has: nobody knows what they cost,
+ * because nothing recorded it. It needs no marker of its own to stay correct,
+ * and it is not fresh-shaped, so the accumulator does the right thing without
+ * being told about this path at all.
+ *
  * See ses_005-deterministic-replay design §2 + §5.2.
  */
 export function projectEmergencyToCheckpoint(dump: EmergencySaveData): IterationCheckpoint {
@@ -64,7 +85,7 @@ export function projectEmergencyToCheckpoint(dump: EmergencySaveData): Iteration
 		iteration: dump.currentIteration,
 		messages: dump.messages,
 		tokenUsage: dump.tokenUsage,
-		costInfo: { ...ZERO_COST },
+		costInfo: { ...ZERO_COST, unpricedTokens: dump.tokenUsage.totalTokens },
 		guardState: {
 			iterationCount: dump.currentIteration,
 			elapsedMs: Math.max(0, dump.savedAt - dump.startedAt),

package/src/runtime/query/guard.ts

@@ -92,6 +92,7 @@ export class GuardCoordinator {
 			aborted: abortSignal.aborted,
 			totalTokens: runMgr.tokenUsage.totalTokens,
 			totalCost: runMgr.costInfo.totalCost,
+			unpricedTokens: runMgr.costInfo.unpricedTokens,
 			currentIteration: runMgr.currentIteration,
 			startTime: this.startTime,
 		}

package/src/runtime/query/index.ts

@@ -16,6 +16,7 @@ import type { CompactionConfig } from '../../config/runtime.js'
 import { TOOL_OUTPUT_DIR_NAME } from '../../constants/tools/index.js'
 import { EmergencySaveManager } from '../../manager/run/emergency.js'
 import type { RunPersistence } from '../../manager/run/persistence.js'
+import { resolveModelPricing } from '../../pricing/index.js'
 import { resolveProviderCapabilities } from '../../provider/capabilities.js'
 import {
 	type ProviderChainMember,
@@ -607,6 +608,46 @@ function assertCostIsAttributable(
 	})
 }
 
+/**
+ * Refuse a budget that cannot be measured.
+ *
+ * `runConfig.costLimitUsd` is enforced against `costInfo.totalCost`, and that
+ * total only moves for tokens something has a rate for. A model no rate card
+ * covers therefore produced a limit that could never trip — a host that set a
+ * cost cap had no cost cap, and nothing said so. That was every run before the
+ * price catalogue existed, which is how it went unnoticed.
+ *
+ * Refusing at the front is the cheap half of the answer: it costs the caller
+ * nothing, fires before any spend, and names both ways out. The other half is
+ * the `cost_unmeasurable` stop, for the models this cannot see — a step naming
+ * its own, or a chain member declaring one.
+ *
+ * This is the same shape `advisory/budget.ts` already applies to
+ * `AdvisoryBudget.maxCostPerRun`, one layer down, and for the same reason. The
+ * run path simply never had it.
+ */
+function assertBudgetIsMeasurable(params: QueryParams): void {
+	const limit = params.runConfig.costLimitUsd
+	if (limit === undefined || limit <= 0) return
+	// A host-supplied table prices whatever it is pointed at, so a caller who
+	// brought one has answered the question themselves.
+	if (params.pricing !== undefined) return
+	const model = params.runConfig.model
+	if (resolveModelPricing(params.provider.id, model) !== undefined) return
+
+	throw new NamzuError({
+		code: 'invalid_config',
+		message:
+			`runConfig.costLimitUsd is set to ${limit}, but no rate is known for model "${model}" on ` +
+			`provider "${params.provider.id}". The limit is enforced against the run's accumulated ` +
+			'cost, and tokens with no rate never reach that total — so the budget would read as ' +
+			'satisfied for the whole run and stop nothing. Either pass `pricing` to declare the rate ' +
+			'yourself, add the model to packages/sdk/src/pricing/rates.source.json, or drop ' +
+			'`costLimitUsd` and bound the run with `tokenBudget`, which is measurable here.',
+		details: { model, providerId: params.provider.id, costLimitUsd: limit },
+	})
+}
+
 export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run> {
 	// Boot-time filesystem migration (session-hierarchy.md §13.4.1). First
 	// call per process per root actually runs; subsequent calls short-circuit
@@ -639,6 +680,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		...(params.fallbackProviders ?? []),
 	]
 	assertCostIsAttributable(chain, params.pricing)
+	assertBudgetIsMeasurable(params)
 	const withRetry = (provider: LLMProvider): LLMProvider =>
 		params.retry === false
 			? provider

package/src/runtime/query/iteration/index.ts

@@ -461,7 +461,17 @@ export class IterationOrchestrator {
 					})()
 
 					// Main-loop turn: also records the prompt size compaction reads.
-					runMgr.recordTurnUsage(response.usage)
+					//
+					// `servedBy` is what prices it, and it is the exact pair —
+					// the member at the cursor when the stream ended, and the
+					// model it was asked for. This is the seam that ended the
+					// always-zero cost: the rate lookup happens per turn,
+					// against who actually answered, rather than against one
+					// table the run was constructed with.
+					runMgr.recordTurnUsage(response.usage, {
+						providerId: servedBy.providerId,
+						model: servedBy.model,
+					})
 
 					// The turn went through, so the run is not sitting on an
 					// irreducible prompt any more. Re-arm relief for the next one.
@@ -1529,7 +1539,10 @@ export class IterationOrchestrator {
 				}),
 			)
 
-			this.ctx.runMgr.accumulateUsage(response.usage)
+			this.ctx.runMgr.accumulateUsage(response.usage, {
+				providerId: this.ctx.runMgr.servingProviderId,
+				model,
+			})
 
 			const assistantMsg = createAssistantMessage(response.message.content)
 			this.ctx.runMgr.pushMessage(assistantMsg)

package/src/runtime/query/iteration/phases/advisory.ts

@@ -117,7 +117,15 @@ export async function runAdvisoryPhase(
 		// `tokenBudget: 200_000` and an `on_error` trigger could send well
 		// past 200k and never trip `token_budget`. The usage is already in
 		// hand — this just tells the accountant about it.
-		ctx.runMgr.accumulateUsage(executionResult.usage)
+		// Priced against the ADVISOR's own driver and model, not the run's. An
+		// advisor carries its own `provider`, so attributing its tokens to
+		// whoever is serving the main loop would price one vendor's work at
+		// another's card — which is the class of quiet wrongness the whole
+		// catalogue exists to remove, and it would be invisible here.
+		ctx.runMgr.accumulateUsage(executionResult.usage, {
+			providerId: advisor.provider.id,
+			model: advisor.model,
+		})
 
 		advisoryCtx.recordCall({
 			advisorId: advisor.id,

package/src/runtime/query/iteration/phases/compaction.ts

@@ -542,19 +542,29 @@ export async function runCompactionCheck(
 	let compactedContent: string
 
 	if (config.llmVerification && manager.slotCount() < config.richStateThreshold) {
+		// Named once and used twice on purpose. The model the summariser is
+		// asked for is also the model its tokens are priced at, and computing
+		// the two separately is how they drift — a router that sends compaction
+		// to a cheap model while the bill is written against the expensive one
+		// is a mistake with no symptom.
+		const compactionModel = resolveTaskModel('compaction', ctx.taskRouter, ctx.runConfig.model)
 		compactedContent = await buildVerifiedSummary(
 			manager,
 			olderMessages,
 			ctx.provider,
 			config,
-			(usage) => ctx.runMgr.accumulateUsage(usage),
+			(usage) =>
+				ctx.runMgr.accumulateUsage(usage, {
+					providerId: ctx.runMgr.servingProviderId,
+					model: compactionModel,
+				}),
 			// The one model call a run makes that the user never asked for. It
 			// reads a transcript and writes a summary, which is the cheapest
 			// thing a small model does well, and it fires on exactly the long
 			// runs where the primary model is most expensive. `taskRouter` had
 			// been accepted, validated and threaded through four types since it
 			// was added, and nothing ever consulted it.
-			resolveTaskModel('compaction', ctx.taskRouter, ctx.runConfig.model),
+			compactionModel,
 		)
 	} else {
 		compactedContent = serializeState(manager.getState())

package/src/store/run/conformance.ts

@@ -177,11 +177,17 @@ const FOREIGN_TENANT = 'tnt_conformance_other' as TenantId
 /** Fixed instant, so every expiry in a case is judged against one clock. */
 const NOW = 5_000_000
 
+/**
+ * A run that cost nothing and has nothing unaccounted for — the shape a store
+ * has to round-trip, not a claim about any real run. Carries no rate fields,
+ * matching `ZERO_COST`: a store fixture that invents `inputCostPer1M: 0` would
+ * be asserting a rate card of zero, which now means "this model is free"
+ * rather than "no rate was applied".
+ */
 const NO_COST: CostInfo = {
-	inputCostPer1M: 0,
-	outputCostPer1M: 0,
 	totalCost: 0,
 	cacheDiscount: 0,
+	unpricedTokens: 0,
 }
 
 let checkpointSeq = 0

package/src/types/common/index.ts

@@ -74,10 +74,46 @@ export function mergeTokenUsage(current: TokenUsage, next: TokenUsage): TokenUsa
 }
 
 export interface CostInfo {
-	inputCostPer1M: number
-	outputCostPer1M: number
+	/**
+	 * The input rate this total was accumulated at — present only when ONE rate
+	 * card describes the whole total.
+	 *
+	 * Absent means "no single rate describes this", not "zero". Three ways to
+	 * get there: nothing has been accumulated yet, the run spanned two
+	 * differently-priced models, or part of it was accumulated at no known rate
+	 * at all. This is the same contract {@link TokenUsage.reasoningTokens} uses
+	 * one field up, for the same reason — a number invented to fill the slot
+	 * would be indistinguishable from a measured one.
+	 *
+	 * The field used to be required, and a run that swapped models reported
+	 * whichever card was applied last, which is a claim about the whole total
+	 * that was true of only part of it.
+	 */
+	inputCostPer1M?: number
+	/** As {@link CostInfo.inputCostPer1M}, for output tokens. */
+	outputCostPer1M?: number
 	totalCost: number
 	cacheDiscount: number
+	/**
+	 * Tokens accumulated at no known rate, so `totalCost` does not include what
+	 * they cost.
+	 *
+	 * This exists so a consumer can tell "this run cost nothing" from "nobody
+	 * knows what this run cost". Reporting the second as zero is the defect the
+	 * price catalogue was added to fix, one level down: a total that is always
+	 * zero and a total that is zero because it is unknown look identical, and
+	 * `runConfig.costLimitUsd` is enforced against both.
+	 *
+	 * - `totalCost: 0, unpricedTokens: 0` — the run genuinely cost nothing
+	 *   (local inference bills per token exactly never).
+	 * - `totalCost: 0, unpricedTokens: 4210` — nobody knows.
+	 * - `totalCost: 0.12, unpricedTokens: 900` — partly known; the total is a
+	 *   floor, not the answer.
+	 *
+	 * A count rather than a flag because a run mixes turns: a step can name its
+	 * own model and a provider chain can swap members mid-run.
+	 */
+	unpricedTokens: number
 }
 
 export interface PlatformError {

package/src/types/run/stop-reason.ts

@@ -2,6 +2,36 @@ export type StopReason =
 	| 'end_turn'
 	| 'token_budget'
 	| 'cost_limit'
+	/**
+	 * A `costLimitUsd` was set and part of the run ran at a rate nobody has, so
+	 * the limit could not be measured.
+	 *
+	 * Distinct from `cost_limit`, and the distinction is the reason this value
+	 * exists: nothing was overspent. Reporting `cost_limit` would send the
+	 * reader to look at spend that was never computed, and would hide the one
+	 * fact they need — that the budget they configured was unenforceable for
+	 * part of this run.
+	 *
+	 * `query()` refuses the same combination up front, so this is the case
+	 * preflight cannot see: a step naming its own model, or a chain member
+	 * declaring one, arriving at a model the price catalogue has no row for.
+	 * `costInfo.unpricedTokens` says how much of the run it covers.
+	 *
+	 * ## The closing call is outside the budget, deliberately
+	 *
+	 * Every hard stop is followed by one more model call — `requestFinalResponse`
+	 * asks for a closing summary, and the guard does not run again before or
+	 * after it. That is pre-existing and true of `cost_limit` and
+	 * `token_budget` alike, and it is stated here rather than left to be
+	 * discovered because for THIS reason it cannot be otherwise: the model that
+	 * triggered the stop is by definition one with no rate, so the closing
+	 * call's cost is unmeasurable by construction. Bounding it would mean
+	 * refusing to close the run at all, which loses the work.
+	 *
+	 * Its tokens are counted, so `costInfo.unpricedTokens` includes them and
+	 * the run reports honestly what it could not price.
+	 */
+	| 'cost_unmeasurable'
 	| 'timeout'
 	| 'max_iterations'
 	| 'cancelled'

package/src/utils/cost.ts

@@ -1,42 +1,195 @@
 import { ZERO_COST } from '../constants/limits.js'
 import type { CostInfo, TokenUsage } from '../types/common/index.js'
 
+/**
+ * What a driver's cache tokens cost, and what they mean.
+ *
+ * `promptIncludesCacheReads` is a property of the DRIVER, not of the model, and
+ * it is why this is a nested object rather than two more rate fields. The
+ * drivers in this repository disagree about it: two report `promptTokens`
+ * excluding cache reads and charge them on top, one reports `promptTokens`
+ * already containing them. Applying a read rate without knowing which one you
+ * have is wrong by the entire cache volume, in a direction that changes with
+ * whoever served the turn — so the fact travels with the rates and is never
+ * inferred.
+ */
+export interface CacheRates {
+	/**
+	 * `true`: `usage.cachedTokens` is a SUBSET of `usage.promptTokens`, so the
+	 * billable input is the difference.
+	 * `false`: they are additional to it.
+	 */
+	readonly promptIncludesCacheReads: boolean
+	readonly readCostPer1M: number
+	/**
+	 * Absent when the driver never reports a cache write. Tokens that arrive
+	 * anyway are counted as unpriced rather than charged at some neighbouring
+	 * rate, so a driver that starts reporting them surfaces as a gap instead of
+	 * a quietly wrong total.
+	 */
+	readonly writeCostPer1M?: number
+}
+
 export interface ModelPricing {
 	inputCostPer1M: number
 	outputCostPer1M: number
+	/**
+	 * Absent means the caller declared a two-rate card and gets a two-rate
+	 * answer: prompt and completion tokens are priced, and cache tokens are
+	 * left inside whichever of those the driver already counted them in. That
+	 * is the host-supplied case and it is a declaration, not a guess on our
+	 * part. The catalogue always supplies this.
+	 */
+	cache?: CacheRates
 }
 
 export { ZERO_COST }
 
-export function calculateCost(
-	usage: TokenUsage,
-	pricing: ModelPricing,
-	cacheDiscount = 0,
-): CostInfo {
-	const inputCost = (usage.promptTokens / 1_000_000) * pricing.inputCostPer1M
-	const outputCost = (usage.completionTokens / 1_000_000) * pricing.outputCostPer1M
-	const gross = inputCost + outputCost
+interface Priced {
+	readonly cost: number
+	/** What the cache reads saved against paying the full input rate. */
+	readonly cacheDiscount: number
+	/** Tokens this rate card had no rate for. */
+	readonly unpriced: number
+}
+
+function priceUsage(usage: TokenUsage, pricing: ModelPricing): Priced {
+	const perMillion = (tokens: number, rate: number) => (tokens / 1_000_000) * rate
+
+	const cache = pricing.cache
+	if (cache === undefined) {
+		return {
+			cost:
+				perMillion(usage.promptTokens, pricing.inputCostPer1M) +
+				perMillion(usage.completionTokens, pricing.outputCostPer1M),
+			cacheDiscount: 0,
+			unpriced: 0,
+		}
+	}
+
+	// Never negative: a driver that reports more cached tokens than prompt
+	// tokens is contradicting itself, and clamping keeps that from turning into
+	// a credit on the bill.
+	const billableInput = cache.promptIncludesCacheReads
+		? Math.max(0, usage.promptTokens - usage.cachedTokens)
+		: usage.promptTokens
 
+	const writesRated = cache.writeCostPer1M !== undefined
+
+	return {
+		cost:
+			perMillion(billableInput, pricing.inputCostPer1M) +
+			perMillion(usage.completionTokens, pricing.outputCostPer1M) +
+			perMillion(usage.cachedTokens, cache.readCostPer1M) +
+			(writesRated ? perMillion(usage.cacheWriteTokens, cache.writeCostPer1M as number) : 0),
+		// Reported, not subtracted. The saving is already inside `cost` — the
+		// reads were charged at the read rate rather than the input rate — so
+		// taking it off again would double-count it. This field was previously
+		// declared, defaulted to zero at both call sites, and passed by nobody;
+		// it now carries the one quantity it was always named for.
+		cacheDiscount: perMillion(usage.cachedTokens, pricing.inputCostPer1M - cache.readCostPer1M),
+		unpriced: writesRated ? 0 : usage.cacheWriteTokens,
+	}
+}
+
+export function calculateCost(usage: TokenUsage, pricing: ModelPricing): CostInfo {
+	const priced = priceUsage(usage, pricing)
 	return {
 		inputCostPer1M: pricing.inputCostPer1M,
 		outputCostPer1M: pricing.outputCostPer1M,
-		totalCost: gross - cacheDiscount,
-		cacheDiscount,
+		totalCost: priced.cost,
+		cacheDiscount: priced.cacheDiscount,
+		unpricedTokens: priced.unpriced,
 	}
 }
 
+/**
+ * Whether `current` is a total nothing has been added to yet.
+ *
+ * All three conditions, not one. A run whose only turn so far was unpriced has
+ * a zero total and no rate fields too, and adopting the next turn's rate card
+ * as though it described the whole total would be exactly the wrong claim.
+ *
+ * This predicate is only sound while every writer of a `CostInfo` goes through
+ * this module or states the truth in its vocabulary. One did not:
+ * `projectEmergencyToCheckpoint` wrote `ZERO_COST` beside a real, non-zero
+ * `tokenUsage`, which is byte-identical to a fresh total — so a run resumed
+ * from an emergency dump would have adopted its next turn's rate card as
+ * covering spend that happened before the crash. That projection now records
+ * the pre-crash tokens as unpriced, which is both true and, usefully, not
+ * fresh-shaped.
+ */
+function isFresh(current: CostInfo): boolean {
+	return (
+		current.totalCost === 0 &&
+		current.unpricedTokens === 0 &&
+		current.inputCostPer1M === undefined &&
+		current.outputCostPer1M === undefined
+	)
+}
+
+/**
+ * The rate fields that honestly describe `current + pricing`.
+ *
+ * Kept when one card still covers the whole total; dropped when it does not.
+ * Dropping rather than overwriting is the change: the previous version wrote
+ * the incoming card over whatever was there, so a run that swapped models
+ * reported the last card applied as though it had priced every token.
+ *
+ * Equal-but-distinct cards are treated as one, deliberately. Two models at the
+ * same published rate produce a total that a single rate card DOES describe,
+ * which is the only claim these two fields make — they name a rate, not a
+ * model, and `Run.steps[].servedBy` carries which model served each turn.
+ */
+function ratesFor(
+	current: CostInfo,
+	pricing: ModelPricing,
+): Pick<CostInfo, 'inputCostPer1M' | 'outputCostPer1M'> {
+	const incoming = {
+		inputCostPer1M: pricing.inputCostPer1M,
+		outputCostPer1M: pricing.outputCostPer1M,
+	}
+	if (isFresh(current)) return incoming
+	if (
+		current.inputCostPer1M === pricing.inputCostPer1M &&
+		current.outputCostPer1M === pricing.outputCostPer1M
+	) {
+		return incoming
+	}
+	return {}
+}
+
 export function accumulateCost(
 	current: CostInfo,
 	additionalUsage: TokenUsage,
 	pricing: ModelPricing,
-	cacheDiscount = 0,
 ): CostInfo {
-	const additional = calculateCost(additionalUsage, pricing, cacheDiscount)
+	const priced = priceUsage(additionalUsage, pricing)
+	const rates = priced.unpriced > 0 ? {} : ratesFor(current, pricing)
 	return {
-		inputCostPer1M: pricing.inputCostPer1M,
-		outputCostPer1M: pricing.outputCostPer1M,
-		totalCost: current.totalCost + additional.totalCost,
-		cacheDiscount: current.cacheDiscount + additional.cacheDiscount,
+		...rates,
+		totalCost: current.totalCost + priced.cost,
+		cacheDiscount: current.cacheDiscount + priced.cacheDiscount,
+		unpricedTokens: current.unpricedTokens + priced.unpriced,
+	}
+}
+
+/**
+ * Record tokens that were consumed at a rate nobody has.
+ *
+ * The alternative was to add nothing and leave the total alone, which is how
+ * every run came to report `$0.00` for work that cost real money. Counting the
+ * tokens instead makes the gap a fact the caller can read and the budget guard
+ * can refuse on, rather than an absence that looks like an answer.
+ *
+ * The rate fields go, if they were there: a total that omits part of a run is
+ * not described by any single card.
+ */
+export function accumulateUnpricedCost(current: CostInfo, additionalUsage: TokenUsage): CostInfo {
+	return {
+		totalCost: current.totalCost,
+		cacheDiscount: current.cacheDiscount,
+		unpricedTokens: current.unpricedTokens + additionalUsage.totalTokens,
 	}
 }
 
@@ -45,3 +198,20 @@ export function formatCost(usd: number): string {
 	if (usd < 0.01) return `$${usd.toFixed(4)}`
 	return `$${usd.toFixed(2)}`
 }
+
+/**
+ * How a total should be shown, given what is and is not known about it.
+ *
+ * Exists so that no surface has to re-derive the free/unknown distinction from
+ * two fields and get it subtly wrong. `@namzu/cli` printed
+ * `'$0.0000 (this provider reported no price)'` for every run, because every
+ * run was unpriced; now the two cases really are different and the string has
+ * to follow.
+ */
+export function describeCost(cost: CostInfo): string {
+	if (cost.unpricedTokens === 0) return formatCost(cost.totalCost)
+	if (cost.totalCost === 0) {
+		return `unknown (${cost.unpricedTokens} tokens at no known rate)`
+	}
+	return `at least ${formatCost(cost.totalCost)} (${cost.unpricedTokens} tokens at no known rate)`
+}