@namzu/sdk 21.1.0 → 22.1.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.
@@ -862,8 +872,9 @@ export class IterationOrchestrator {
 
 					// A successful `structured_output` call IS the answer, so the
 					// run ends here rather than paying for another turn whose only
-					// job would be to restate it.
-					if (this.captureStructuredOutput(reviewOutcome.results)) {
+					// job would be to restate it — unless it shared its turn with
+					// other calls, which relays instead. See the method.
+					if (this.captureStructuredOutput(reviewOutcome.results, response)) {
 						this.ctx.log.info('Structured output produced — ending run', {
 							runId: runMgr.id,
 							iteration: iterationNum,
@@ -1357,14 +1368,6 @@ export class IterationOrchestrator {
 		return this.ctx.structuredOutput !== undefined && !this.structuredOutputDone
 	}
 
-	/**
-	 * Record the structured output if this batch produced one.
-	 *
-	 * The tool validates against the Zod schema before its `execute` runs,
-	 * so reaching here successfully means the value is already valid — a
-	 * failed parse comes back as an error result and simply does not
-	 * satisfy the demand, which sends the loop round again.
-	 */
 	/**
 	 * The answer a terminal tool produced, or `undefined` to keep looping.
 	 *
@@ -1405,10 +1408,67 @@ export class IterationOrchestrator {
 		return hit
 	}
 
-	private captureStructuredOutput(results: readonly ToolCallOutcome[]): boolean {
+	/**
+	 * Record the structured output if this batch produced one.
+	 *
+	 * The tool validates against the Zod schema before its `execute` runs,
+	 * so reaching here successfully means the value is already valid — a
+	 * failed parse comes back as an error result and simply does not
+	 * satisfy the demand, which sends the loop round again.
+	 *
+	 * Narrow in the same way {@link terminalToolOutput} is, for its stated
+	 * reason and one that is sharper here. The neighbour refuses a shared
+	 * turn because "a model that asked for other work meant to see those
+	 * results". That applies unchanged. But the batch has ALREADY executed
+	 * by the time this runs — `runToolReview` settles it, side effects
+	 * included, before either of these is consulted — so settling here is
+	 * worse than discarding an answer the model wanted: the work happened,
+	 * its results went into the transcript, and the run ended before any
+	 * model turn could read them. Nothing consumed what was spent, and
+	 * nothing said so.
+	 *
+	 * Sharper, too, because of WHEN this value was produced. The model
+	 * emitted its final answer in the same turn as a request for
+	 * information it had not yet received — it would not have asked
+	 * otherwise — so the answer is under-informed on the model's own
+	 * account, and settling ships it as final.
+	 *
+	 * So: relay, do not settle. The results are already in the transcript,
+	 * the demand is still unsatisfied, and the next turn produces the
+	 * answer with them in hand. Refusing to EXECUTE the batch was the other
+	 * candidate and is wrong — the defect is not that the tools ran, it is
+	 * that nobody read them, and denying a model work it asked for to
+	 * protect an answer it has not finished forming gives up a real
+	 * capability for nothing. The price is one extra turn when the paired
+	 * call was a pure side effect whose result the model did not need;
+	 * that is the price `terminalToolOutput` already pays, and a model
+	 * avoids it by not pairing.
+	 *
+	 * NOT charged to `maxRetries`. That budget bounds a model that cannot
+	 * satisfy the SCHEMA, and this one did. A run reading two files a turn
+	 * while optimistically attaching its answer is making progress, and it
+	 * must not die reported as `structured_output_failed` — a failure that
+	 * did not happen. `maxIterations` is the bound for a model that keeps
+	 * doing work, and it is the bound the neighbour relies on for the
+	 * identical pathology.
+	 */
+	private captureStructuredOutput(
+		results: readonly ToolCallOutcome[],
+		response: ChatCompletionResponse,
+	): boolean {
 		if (!this.needsStructuredOutput()) return false
 		const hit = results.find((r) => r.toolName === STRUCTURED_OUTPUT_TOOL_NAME && !r.isError)
 		if (!hit) return false
+
+		const callCount = response.message.toolCalls?.length ?? 0
+		if (callCount > 1) {
+			this.ctx.log.info('Structured output shared its turn — relaying instead of settling', {
+				runId: this.ctx.runMgr.id,
+				callsInTurn: callCount,
+			})
+			return false
+		}
+
 		try {
 			this.ctx.runMgr.setStructuredOutput(JSON.parse(hit.output))
 		} catch {
@@ -1529,7 +1589,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/agent/supervisor.ts

@@ -6,6 +6,7 @@ import type { LLMProvider } from '../provider/index.js'
 import type { TaskRouterConfig } from '../router/index.js'
 import type { SandboxProvider } from '../sandbox/index.js'
 import type { Skill } from '../skills/index.js'
+import type { StructuredOutputConfig } from '../structured-output/index.js'
 import type { ToolRegistryContract } from '../tool/index.js'
 import type { VerificationGateConfig } from '../verification/index.js'
 import type { BaseAgentConfig, BaseAgentResult } from './base.js'
@@ -172,6 +173,35 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	 */
 	compactionConfig?: CompactionConfig
 
+	/**
+	 * Demand that the supervisor's own final answer match a schema.
+	 *
+	 * `ReactiveAgent` has forwarded this since the field existed and the
+	 * supervisor never took it, with nothing in this file saying why —
+	 * which in a file where `maxDepth`, `allowDelegation`,
+	 * `maxToolConcurrency` and `siblingFailurePolicy` each carry a
+	 * paragraph of argument is the signature of an oversight, not of a
+	 * decision. The kernel path is archetype-blind: `drainQuery` registers
+	 * `structured_output` from this config and the loop captures it, so the
+	 * capability was always there and only the hop was missing.
+	 *
+	 * **What it buys, exactly.** Structured output is terminal and
+	 * exclusive by policy: `setStructuredOutput` overwrites `Run.result`
+	 * behind a sticky flag and the run ends on the turn that produces it.
+	 * So this gives a supervisor a schema-constrained FINAL ANSWER and
+	 * nothing more. It does not shape a delegated child's answer — a child
+	 * carries its own config — it does not run alongside prose, and it is
+	 * not a return type for the fan-out. A host wanting typed results from
+	 * the workers sets the schema on the workers.
+	 *
+	 * One consequence a supervisor host in particular should know: the
+	 * answer decides the run, so delegated work still running when it lands
+	 * is walked away from rather than waited for. It is recorded — the run
+	 * names it on `abandonedTaskIds` — but it is not delivered. That is the
+	 * same precedence a terminal tool has, stated in the iteration loop.
+	 */
+	structuredOutput?: StructuredOutputConfig
+
 	/**
 	 * Optional neutral working-memory seam. When set, the SDK re-renders the
 	 * provider's string into a single pinned leading system message every

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'