@namzu/sdk 62.4.0 → 62.6.0

package/src/runtime/query/prepare-turn.ts

@@ -332,8 +332,13 @@ export async function prepareTurn(params: QueryParams): Promise<PreparedTurn> {
 	const promptCache = params.promptCache
 	const taskScheduler = params.taskScheduler
 	const streamIdleTimeoutMs = resolveStreamIdleTimeoutMs(params.turnConfig.streamIdleTimeoutMs)
-	const maxRequestRichContentBytes = resolveMaxRequestRichContentBytes(
+	// Validated here, at the door, but only the caller's own override is kept on
+	// the turn: the provider's declaration is read where it is used (see
+	// `IterationOrchestrator.richContentBudget`), so it follows the provider
+	// that serves the turn rather than being pinned by the first one.
+	resolveMaxRequestRichContentBytes(
 		params.turnConfig.maxRequestRichContentBytes,
+		params.provider.capabilities?.maxRequestRichContentBytes,
 	)
 	const sandboxTeardownTimeoutMs = resolveSandboxTeardownTimeoutMs(params.sandboxTeardownTimeoutMs)
 	// Persist the EFFECTIVE value, not only an override. A turn replayed after a
@@ -343,7 +348,6 @@ export async function prepareTurn(params: QueryParams): Promise<PreparedTurn> {
 	const turnConfig: TurnConfig = {
 		...params.turnConfig,
 		streamIdleTimeoutMs,
-		maxRequestRichContentBytes,
 	}
 
 	// The turn's one correlated logger, built before anything below needs

package/src/runtime/query/request-rich-content.ts

@@ -12,8 +12,17 @@ export const DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES = 24 * 1024 * 1024
 
 const MAX_REQUEST_RICH_CONTENT_BYTES = Number.MAX_SAFE_INTEGER
 
-export function resolveMaxRequestRichContentBytes(value: number | undefined): number {
-	const resolved = value ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES
+/**
+ * The budget for one turn: the caller's `turnConfig.maxRequestRichContentBytes`
+ * when set, else the one the provider declares for its own wire limit
+ * (`ProviderCapabilities.maxRequestRichContentBytes`), else the kernel default.
+ * The override always wins, so a host can tighten or loosen what a driver declares.
+ */
+export function resolveMaxRequestRichContentBytes(
+	value: number | undefined,
+	providerDeclared?: number,
+): number {
+	const resolved = value ?? providerDeclared ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES
 	if (
 		!Number.isSafeInteger(resolved) ||
 		resolved < 0 ||

package/src/turn/index.ts

@@ -23,7 +23,7 @@ export type { LimitCheckerState, LimitCheckResult } from './LimitChecker.js'
 
 export { SESSION_MEMORY_TAG, createMemoryPromoter } from './memory-promoter.js'
 export type { MemoryPromoterOptions, SessionMemoryCategory } from './memory-promoter.js'
-export { createMemoryRecallStep } from './memory-recall.js'
+export { createMemoryRecallStep, recalledMemoryIds } from './memory-recall.js'
 export type {
 	MemoryRecallOptions,
 	MemorySelection,

package/src/turn/memory-recall.ts

@@ -80,6 +80,12 @@ export interface MemoryRecallOptions {
 	readonly minCoverage?: number
 	/** Upper bound on the selector, in ms; the signal it is given aborts then. Default 2,500. */
 	readonly selectTimeoutMs?: number
+	/**
+	 * Ids recall must not offer, read afresh on every request. A host keeps a
+	 * set-aside list here (records a refused request carried) and lifts it when
+	 * the person restores a record. A throw reads as an empty list.
+	 */
+	readonly excluded?: () => Iterable<string> | Promise<Iterable<string>>
 }
 
 /** What a selector may know about a record: never its body. */
@@ -126,6 +132,27 @@ const OTHERS_PLURAL = (count: number): string =>
 export const RECALLED_MEMORY_ENTRY_KEY = 'memory'
 
 /** The `id@updatedAt` of every record the entries still in the history carry. */
+/**
+ * The ids of the records the `memory` entries carry, in the order they were
+ * recorded and without repeats. `entries` are bodies as `turnContextEntries`
+ * returns them.
+ */
+export function recalledMemoryIds(entries: readonly string[]): string[] {
+	const ids = new Set<string>()
+	for (const entry of entries) {
+		for (const line of entry.split('\n')) {
+			if (!line.startsWith('{')) continue
+			try {
+				const parsed = JSON.parse(line) as { id?: unknown }
+				if (typeof parsed.id === 'string') ids.add(parsed.id)
+			} catch {
+				// a line of the entry that is not a record
+			}
+		}
+	}
+	return [...ids]
+}
+
 function recordedRecords(entries: readonly string[]): Set<string> {
 	const seen = new Set<string>()
 	for (const entry of entries) {
@@ -377,8 +404,12 @@ export function createMemoryRecallStep(options: MemoryRecallOptions): PrepareSte
 		latestUserMessage,
 		contextBudget,
 		signal,
+		withheldKeys,
 	}) => {
 		signal?.throwIfAborted()
+		// A refused request was re-run without the memories it carried; adding
+		// them again would be refused again.
+		if (withheldKeys?.includes(RECALLED_MEMORY_ENTRY_KEY)) return undefined
 		// Leave room for the current request and response. The kernel supplies
 		// an estimate; using one character per remaining token is deliberately
 		// conservative for this optional text, not a billing/tokenizer claim.
@@ -484,6 +515,14 @@ export function createMemoryRecallStep(options: MemoryRecallOptions): PrepareSte
 		}
 		const recall = async (): Promise<Recalled> => {
 			const shown: RecalledMemory[] = []
+			let excludedIds: ReadonlySet<string> = new Set()
+			if (options.excluded) {
+				try {
+					excludedIds = new Set(await options.excluded())
+				} catch {
+					// An unreadable list excludes nothing.
+				}
+			}
 			const page = await options.store.list({
 				query: terms.join(' '),
 				status: 'active',
@@ -501,6 +540,7 @@ export function createMemoryRecallStep(options: MemoryRecallOptions): PrepareSte
 			let block = lead
 			const fresh = page.entries
 				.filter((entry) => entry.status === 'active')
+				.filter((entry) => !excludedIds.has(entry.id))
 				.filter((entry) => !known.has(`${entry.id}@${entry.updatedAt}`))
 			const candidates = fresh.slice(0, shortlist)
 			const picks = await choose(candidates)

package/src/types/agent/base.ts

@@ -226,6 +226,8 @@ export interface BaseAgentConfig {
 	 */
 	thinking?: import('../provider/index.js').ThinkingConfig
 	effort?: import('../provider/index.js').ReasoningEffort
+	/** Inference speed; see {@link import('../session/config.js').TurnConfig.speed}. */
+	speed?: import('../provider/index.js').InferenceSpeed
 	/** How the turn bounds its reasoning; see {@link import('../session/config.js').TurnConfig.reasoning}. */
 	reasoning?: import('../session/config.js').TurnConfig['reasoning']
 	/** Ask once for a check of edits before a turn ends; see {@link import('../session/config.js').TurnConfig.completionAudit}. */

package/src/types/agent/query.ts

@@ -100,6 +100,10 @@ export interface QueryAgentConfig extends BaseAgentConfig {
 	maxOutputContinuations?: QueryParams['maxOutputContinuations']
 	/** See {@link QueryParams.refusalFallback}. */
 	refusalFallback?: QueryParams['refusalFallback']
+	/** See {@link QueryParams.withholdOnRefusal}. */
+	withholdOnRefusal?: QueryParams['withholdOnRefusal']
+	/** See {@link QueryParams.withheldKeys}. */
+	withheldKeys?: QueryParams['withheldKeys']
 	maxToolOutputChars?: number
 	maxToolOutputCharsPerMessage?: number
 	retainedToolPreviewChars?: QueryParams['retainedToolPreviewChars']

package/src/types/common/index.ts

@@ -42,6 +42,50 @@ export interface TokenUsage {
 	 * {@link TokenUsage.cacheTtlMs}.
 	 */
 	cacheWriteTtlTokens?: { fiveMin?: number; oneHour?: number }
+
+	/**
+	 * The speed the provider says served this call, when it says. `'fast'` is a
+	 * premium-priced mode, so pricing reads it per call: a per-call fact like
+	 * {@link TokenUsage.cacheTtlMs}, never summed. Absent means standard or
+	 * unreported.
+	 */
+	speed?: import('../provider/chat.js').InferenceSpeed
+
+	/**
+	 * Hosted web searches the provider ran for this call and bills per request.
+	 * Unlike the per-call facts below it IS a count of work done, so it is
+	 * summed across calls. Absent means the provider did not report one.
+	 */
+	webSearchRequests?: number
+
+	/**
+	 * The service tier the provider says served this call (`standard`,
+	 * `priority`, `batch`). A per-call fact, never summed. Absent means
+	 * unreported.
+	 */
+	serviceTier?: string
+
+	/** The region the provider says ran this call, when it says. Per call, never summed. */
+	inferenceGeo?: string
+
+	/**
+	 * Why the provider's prompt cache did not serve a prefix it had before, when
+	 * it explains. Per call, never summed. Absent means no miss was explained: the
+	 * provider reported nothing, a pending answer, or a hit.
+	 */
+	cacheMiss?: CacheMiss
+}
+
+/** A prompt-cache miss as the provider explains it. See {@link TokenUsage.cacheMiss}. */
+export interface CacheMiss {
+	/**
+	 * The provider's own reason, e.g. `model_changed`, `system_changed`,
+	 * `tools_changed`, `messages_changed`, `previous_message_not_found`,
+	 * `unavailable`.
+	 */
+	reason: string
+	/** Input tokens that missed the cache because of it, when the provider counts them. */
+	missedTokens?: number
 }
 
 export function accumulateTokenUsage(current: TokenUsage, addition: TokenUsage): TokenUsage {
@@ -58,8 +102,12 @@ export function accumulateTokenUsage(current: TokenUsage, addition: TokenUsage):
 		...(current.reasoningTokens !== undefined || addition.reasoningTokens !== undefined
 			? { reasoningTokens: (current.reasoningTokens ?? 0) + (addition.reasoningTokens ?? 0) }
 			: {}),
-		// `cacheTtlMs` and `cacheWriteTtlTokens` are per-call facts and are
-		// deliberately not carried into a sum.
+		...(current.webSearchRequests !== undefined || addition.webSearchRequests !== undefined
+			? { webSearchRequests: (current.webSearchRequests ?? 0) + (addition.webSearchRequests ?? 0) }
+			: {}),
+		// `cacheTtlMs`, `cacheWriteTtlTokens`, `speed`, `serviceTier`,
+		// `inferenceGeo` and `cacheMiss` are per-call facts and are deliberately
+		// not carried into a sum.
 	}
 }
 
@@ -101,6 +149,21 @@ export function mergeTokenUsage(current: TokenUsage, next: TokenUsage): TokenUsa
 		...(next.cacheWriteTtlTokens !== undefined || current.cacheWriteTtlTokens !== undefined
 			? { cacheWriteTtlTokens: next.cacheWriteTtlTokens ?? current.cacheWriteTtlTokens }
 			: {}),
+		...(next.speed !== undefined || current.speed !== undefined
+			? { speed: next.speed ?? current.speed }
+			: {}),
+		...(next.webSearchRequests !== undefined || current.webSearchRequests !== undefined
+			? { webSearchRequests: Math.max(current.webSearchRequests ?? 0, next.webSearchRequests ?? 0) }
+			: {}),
+		...(next.serviceTier !== undefined || current.serviceTier !== undefined
+			? { serviceTier: next.serviceTier ?? current.serviceTier }
+			: {}),
+		...(next.inferenceGeo !== undefined || current.inferenceGeo !== undefined
+			? { inferenceGeo: next.inferenceGeo ?? current.inferenceGeo }
+			: {}),
+		...(next.cacheMiss !== undefined || current.cacheMiss !== undefined
+			? { cacheMiss: next.cacheMiss ?? current.cacheMiss }
+			: {}),
 	}
 }
 

package/src/types/provider/chat.ts

@@ -106,6 +106,15 @@ export interface ChatCompletionParams {
 	 * that narrower set according to their documented provider policy.
 	 */
 	effort?: ReasoningEffort
+
+	/**
+	 * Inference speed. `'fast'` asks a provider for its premium low-latency
+	 * mode, billed at a multiple of the standard rate; absent and `'standard'`
+	 * are the same request. A driver with no such mode, or a model without it,
+	 * must refuse `'fast'` rather than serve it at standard speed and let the
+	 * caller believe it was honoured.
+	 */
+	speed?: InferenceSpeed
 }
 
 export interface ThinkingConfig {
@@ -174,6 +183,9 @@ export interface ThinkingConfig {
  * transport or leave the vendor to refuse an unknown compatible-endpoint
  * extension explicitly.
  */
+/** `'fast'` is a premium low-latency mode; `'standard'` is the ordinary request. See {@link ChatCompletionParams.speed}. */
+export type InferenceSpeed = 'standard' | 'fast'
+
 export type ReasoningEffort =
 	| 'none'
 	| 'minimal'

package/src/types/provider/config.ts

@@ -170,6 +170,14 @@ export interface ProviderCapabilities {
 	 * or the lifetime is the provider's own and cannot be chosen or read).
 	 */
 	cacheTtl?: readonly ('5m' | '1h')[]
+	/**
+	 * The most base64 characters of inline images and documents this provider
+	 * will take in one request, when its wire limit differs from the kernel's
+	 * default (24 MiB). Counts the encoded value, like
+	 * `turnConfig.maxRequestRichContentBytes`, which still overrides it.
+	 * Absent means the kernel default.
+	 */
+	maxRequestRichContentBytes?: number
 }
 
 export interface ProviderFactoryResult {

package/src/types/provider/index.ts

@@ -5,6 +5,7 @@ export type {
 	ChatCompletionParams,
 	ChatCompletionResponse,
 	ProviderRefusal,
+	InferenceSpeed,
 	ReasoningEffort,
 	ThinkingConfig,
 } from './chat.js'

package/src/types/session/config.ts

@@ -69,6 +69,17 @@ export interface TurnConfig {
 	 */
 	effort?: import('../provider/index.js').ReasoningEffort
 
+	/**
+	 * Inference speed for every model call in the turn: `'fast'` asks for the
+	 * provider's premium low-latency mode (billed at a multiple of the standard
+	 * rate), absent and `'standard'` are the ordinary request. Turn-level for
+	 * the same reason as {@link TurnConfig.effort}: speeds do not share a
+	 * prompt-cache prefix, so a value that moves between steps pays for a cache
+	 * miss each time. A driver or model without the mode REFUSES `'fast'`
+	 * rather than serving it slowly.
+	 */
+	speed?: import('../provider/index.js').InferenceSpeed
+
 	/**
 	 * How the turn bounds its reasoning. On by default.
 	 *

package/src/types/session/events.ts

@@ -519,7 +519,14 @@ type CoreSessionEvent =
 			/** The model that declined. */
 			model: string
 			providerId: string
-			outcome: 'fallback' | 'retry' | 'declined'
+			outcome: 'fallback' | 'retry' | 'withheld' | 'declined'
+			/**
+			 * Set only with `outcome: 'withheld'`: the recorded-context keys the
+			 * re-run leaves out of the request (see `QueryParams.withholdOnRefusal`).
+			 */
+			withheldKeys?: string[]
+			/** With `'withheld'`: the ids of the recalled memories those entries carried. */
+			withheldMemoryIds?: string[]
 			/** The model the request moves to. Set only with `outcome: 'fallback'`. */
 			fallbackModel?: string
 			/** The provider's own classification, when it gave one. */
@@ -919,6 +926,13 @@ type CoreSessionEvent =
 			 * absent means unknown, and a host must not assume one.
 			 */
 			cache?: { ttlMs: number; touched: boolean }
+			/**
+			 * Why the provider says the latest model call did not read the cache
+			 * prefix it had before, when it explains one. Absent means no miss was
+			 * explained: nothing reported, a pending answer, or a hit. A host that
+			 * shows it should do so quietly; a miss after an edit is ordinary.
+			 */
+			cacheMiss?: { reason: string; missedTokens?: number }
 			/**
 			 * How large the CONTEXT is right now, and how large it may get.
 			 *

package/src/types/session/prepare-step.ts

@@ -98,6 +98,13 @@ export interface PrepareStepContext {
 	}
 	/** Every completed step, in order. */
 	readonly steps: readonly StepResult[]
+	/**
+	 * Recorded-context keys the request leaves out: set aside by a refused
+	 * request (`QueryParams.withholdOnRefusal`) or by the host
+	 * (`QueryParams.withheldKeys`). A stage that records text under one of
+	 * these keys should add nothing now; whatever it records is also left out.
+	 */
+	readonly withheldKeys?: readonly string[]
 
 	/**
 	 * What the stages before this one decided, when several were supplied.

package/src/utils/cost.ts

@@ -41,6 +41,19 @@ export interface ModelPricing {
 	 * part. The catalogue always supplies this.
 	 */
 	cache?: CacheRates
+	/**
+	 * The vendor's published multiple of every rate on this card for a request
+	 * served in fast mode (`TokenUsage.speed === 'fast'`). Absent means there is
+	 * no published fast price: fast usage is then counted as unpriced, never
+	 * charged at the standard rate, which would under-report it.
+	 */
+	fastMultiplier?: number
+	/**
+	 * What the vendor charges per 1,000 hosted web searches
+	 * (`TokenUsage.webSearchRequests`). Absent means no published search price:
+	 * searches are then not part of the total, as before this field existed.
+	 */
+	webSearchCostPer1000?: number
 }
 
 export { ZERO_COST }
@@ -54,6 +67,42 @@ interface Priced {
 }
 
 function priceUsage(usage: TokenUsage, pricing: ModelPricing): Priced {
+	const tokens = priceTokens(usage, pricing)
+	const searches = usage.webSearchRequests ?? 0
+	if (searches === 0 || pricing.webSearchCostPer1000 === undefined) return tokens
+	// Per request, so no speed or tier multiple applies to it.
+	return { ...tokens, cost: tokens.cost + (searches / 1000) * pricing.webSearchCostPer1000 }
+}
+
+/**
+ * Tiers with a published per-token price (anything but `priority` and `batch`; a compatible endpoint may report `default` or `auto`). The vendor lists none for `priority`
+ * (a capacity commitment) or `batch` (a different endpoint), so tokens served
+ * on one are unpriced rather than charged at the standard rate.
+ */
+function isStandardTier(tier: string | undefined): boolean {
+	return tier !== 'priority' && tier !== 'batch'
+}
+
+function priceTokens(usage: TokenUsage, pricing: ModelPricing): Priced {
+	if (!isStandardTier(usage.serviceTier)) {
+		return { cost: 0, cacheDiscount: 0, unpriced: usage.totalTokens }
+	}
+	if (usage.speed === 'fast') {
+		const multiplier = pricing.fastMultiplier
+		if (multiplier === undefined) {
+			return { cost: 0, cacheDiscount: 0, unpriced: usage.totalTokens }
+		}
+		const standard = priceStandard({ ...usage, speed: undefined }, pricing)
+		return {
+			cost: standard.cost * multiplier,
+			cacheDiscount: standard.cacheDiscount * multiplier,
+			unpriced: standard.unpriced,
+		}
+	}
+	return priceStandard(usage, pricing)
+}
+
+function priceStandard(usage: TokenUsage, pricing: ModelPricing): Priced {
 	const perMillion = (tokens: number, rate: number) => (tokens / 1_000_000) * rate
 
 	const cache = pricing.cache