@namzu/sdk 53.2.1 → 54.0.0

package/src/types/common/index.ts

@@ -24,6 +24,24 @@ export interface TokenUsage {
 	 * not zero.
 	 */
 	reasoningTokens?: number
+
+	/**
+	 * How long the provider keeps the prompt cache this call used, in
+	 * milliseconds, as the call itself reported or requested it.
+	 *
+	 * A fact about ONE model call, so it is never summed: {@link accumulateTokenUsage}
+	 * drops it, and {@link mergeTokenUsage} (frames of one streamed call) keeps the
+	 * latest value. Absent means the driver does not report a lifetime (or does
+	 * not cache); a host must not guess one.
+	 */
+	cacheTtlMs?: number
+
+	/**
+	 * Cache-write tokens split by the lifetime they were written with. Present
+	 * only when the provider breaks its write count down. Per call, like
+	 * {@link TokenUsage.cacheTtlMs}.
+	 */
+	cacheWriteTtlTokens?: { fiveMin?: number; oneHour?: number }
 }
 
 export function accumulateTokenUsage(current: TokenUsage, addition: TokenUsage): TokenUsage {
@@ -40,6 +58,8 @@ 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.
 	}
 }
 
@@ -74,6 +94,13 @@ export function mergeTokenUsage(current: TokenUsage, next: TokenUsage): TokenUsa
 		...(current.reasoningTokens !== undefined || next.reasoningTokens !== undefined
 			? { reasoningTokens: Math.max(current.reasoningTokens ?? 0, next.reasoningTokens ?? 0) }
 			: {}),
+		// Frames of one call describe the same cache: the latest report wins.
+		...(next.cacheTtlMs !== undefined || current.cacheTtlMs !== undefined
+			? { cacheTtlMs: next.cacheTtlMs ?? current.cacheTtlMs }
+			: {}),
+		...(next.cacheWriteTtlTokens !== undefined || current.cacheWriteTtlTokens !== undefined
+			? { cacheWriteTtlTokens: next.cacheWriteTtlTokens ?? current.cacheWriteTtlTokens }
+			: {}),
 	}
 }
 

package/src/types/provider/chat.ts

@@ -21,6 +21,14 @@ export type ResponseFormat =
 
 export interface CacheControl {
 	type: 'auto' | 'ephemeral'
+	/**
+	 * How long the provider should keep this prefix cached: `'5m'` (the
+	 * default every provider uses when this is absent) or `'1h'`. Honoured only
+	 * by a driver that has an extended lifetime; others ignore it. The longer
+	 * lifetime is priced higher for the cache write, so asking for it is a cost
+	 * decision, not a translation.
+	 */
+	ttl?: '5m' | '1h'
 }
 
 export interface ChatCompletionParams {

package/src/types/provider/config.ts

@@ -157,6 +157,12 @@ export interface ProviderCapabilities {
 	/** Whether the driver maps document blocks returned by tools onto its result wire. */
 	supportsToolResultDocuments?: boolean
 	maxOutputTokens?: number
+	/**
+	 * Prompt-cache lifetimes the driver can be asked for through
+	 * `cacheControl.ttl`. Absent means the driver offers none (it has no cache,
+	 * or the lifetime is the provider's own and cannot be chosen or read).
+	 */
+	cacheTtl?: readonly ('5m' | '1h')[]
 }
 
 export interface ProviderFactoryResult {

package/src/types/session/checkpoint.ts

@@ -79,6 +79,11 @@ export const TokenUsageSchema = z
 		cachedTokens: count,
 		cacheWriteTokens: count,
 		reasoningTokens: count.optional(),
+		cacheTtlMs: count.optional(),
+		cacheWriteTtlTokens: z
+			.object({ fiveMin: count.optional(), oneHour: count.optional() })
+			.strict()
+			.optional(),
 	})
 	.strict()
 

package/src/types/session/events.ts

@@ -811,6 +811,12 @@ type CoreSessionEvent =
 			turnId: TurnId
 			usage: TokenUsage
 			cost: CostInfo
+			/**
+			 * The prompt cache after the latest model call alone (not the turn
+			 * total above). Present only when the driver reports a lifetime;
+			 * absent means unknown, and a host must not assume one.
+			 */
+			cache?: { ttlMs: number; touched: boolean }
 			/**
 			 * How large the CONTEXT is right now, and how large it may get.
 			 *

package/src/types/session/records.ts

@@ -494,7 +494,7 @@ export const DecisionExpiredRecordSchema = inTurn('decision_expired', {
 export const CompactionRecordSchema = recordSchema('compaction', {
 	compactionId: text.min(1),
 	strategy: text.min(1),
-	trigger: z.enum(['auto', 'manual']),
+	trigger: z.enum(['auto', 'manual', 'idle']),
 	replacesSeqRange: z.tuple([positive, positive]),
 	summary: z.union([z.array(messageBody), spill]),
 	keptMessageIds: z.array(messageId),

package/src/types/tool/presentation.ts

@@ -106,6 +106,16 @@ export type ToolFailureReason =
 	| 'unknown_tool'
 	| 'timed_out'
 	| 'invalid_input'
+	/** An edit or write on a file the conversation never read. */
+	| 'not_read'
+	/** An edit or write based on a copy that has since changed on disk. */
+	| 'changed_on_disk'
+	/** An edit whose text is not in the file. */
+	| 'text_not_found'
+	/** An edit whose text appears more than once. */
+	| 'not_unique'
+	/** The call's arguments did not fit the tool's input schema, so the tool never ran. */
+	| 'invalid_arguments'
 
 /**
  * What a call was about and what came of it, as typed fields.
@@ -126,6 +136,12 @@ export type ToolFacts =
 			/** The command line, on the call. */
 			readonly command?: string
 			readonly exitCode?: number
+			/**
+			 * A non-zero `exitCode` that is the command's answer and not a failure
+			 * (`grep` found nothing, `diff` found a difference): a short plain
+			 * sentence. A host draws the call as having succeeded.
+			 */
+			readonly exitNote?: string
 			readonly timedOut?: boolean
 			/** The signal that ended it, when one did. */
 			readonly signal?: string