@namzu/sdk 53.2.2 → 54.0.0

package/src/tools/builtins/bash.ts

@@ -23,6 +23,7 @@ import { defineTool } from '../defineTool.js'
 import { scrubInheritedEnv } from '../env-scrub.js'
 import { createHostOutputDecoder } from '../host-output.js'
 import { looksBinary, windowText } from '../text-window.js'
+import { judgeExit } from './exit-semantics.js'
 import { jsonStringEscapes } from './json-string-hint.js'
 
 // Namzu owns its own bash timeout knob — `NAMZU_BASH_TIMEOUT_MS` — and
@@ -669,11 +670,14 @@ const BashToolBase = defineTool({
 				.filter(Boolean)
 				.join('\n\n')
 
+			const judged = result.timedOut ? undefined : judgeExit(input.command, result.exitCode)
+			const answered = judged !== undefined && !judged.isError
 			return {
-				success: !result.timedOut && result.exitCode === 0,
+				success: answered,
 				output: output || '(no output)',
 				data: {
 					exitCode: result.exitCode,
+					...(judged?.note ? { exitNote: judged.note } : {}),
 					sandboxed: true,
 					timedOut: result.timedOut,
 					stdoutTruncated: result.stdoutTruncated ?? false,
@@ -681,12 +685,13 @@ const BashToolBase = defineTool({
 				},
 				error: result.timedOut
 					? `Command timed out after ${input.timeout}ms. Any captured output before the deadline is above.`
-					: result.exitCode !== 0
+					: !answered
 						? `Command exited with code ${result.exitCode}`
 						: undefined,
 				facts: commandFacts({
 					command: input.command,
 					exitCode: result.exitCode,
+					...(judged?.note ? { exitNote: judged.note } : {}),
 					timedOut: result.timedOut,
 					stdout: result.stdout,
 					stderr: result.stderr,
@@ -801,35 +806,44 @@ const BashToolBase = defineTool({
 			// and appending this to every result would make the common case noisy
 			// to buy nothing. A failing one is exactly where "authentication
 			// failed" has to be distinguishable from "the variable was withheld".
+			// A status the command uses to answer (no match, files differ) is a
+			// result, not a failure; the model sees it as an ordinary call.
+			const judged =
+				!timedOut && exitCode !== undefined ? judgeExit(input.command, exitCode) : undefined
+			const answered = judged !== undefined && !judged.isError
 			const output = [
 				formatShellOutput(failure.stdout, failure.stderr),
 				clipped.length > 0
 					? `[${clipped.join(' and ')} ${clipped.length === 1 ? 'was' : 'were'} truncated by the host output cap. The omitted output is unavailable in this result.]`
 					: '',
-				describeWithheldEnv(inherited.dropped),
+				answered ? '' : describeWithheldEnv(inherited.dropped),
 			]
 				.filter(Boolean)
 				.join('\n\n')
 
 			return {
-				success: false,
+				success: answered,
 				output: output || '(no output)',
 				data: {
 					...(exitCode !== undefined ? { exitCode } : {}),
+					...(judged?.note ? { exitNote: judged.note } : {}),
 					...(leaveSandbox ? { sandboxed: false, sandboxEscape: true } : {}),
 					timedOut,
 					stdoutTruncated: failure.stdoutTruncated ?? false,
 					stderrTruncated: failure.stderrTruncated ?? false,
 					...(failure.signal ? { signal: failure.signal } : {}),
 				},
-				error: timedOut
-					? `Command timed out after ${input.timeout}ms. Any output it produced before the deadline is above.`
-					: exitCode !== undefined
-						? `Command exited with code ${exitCode}`
-						: `Command failed: ${failure.message}`,
+				error: answered
+					? undefined
+					: timedOut
+						? `Command timed out after ${input.timeout}ms. Any output it produced before the deadline is above.`
+						: exitCode !== undefined
+							? `Command exited with code ${exitCode}`
+							: `Command failed: ${failure.message}`,
 				facts: commandFacts({
 					command: input.command,
 					...(exitCode !== undefined ? { exitCode } : {}),
+					...(judged?.note ? { exitNote: judged.note } : {}),
 					timedOut,
 					...(failure.signal ? { signal: failure.signal } : {}),
 					stdout: failure.stdout ?? '',
@@ -851,6 +865,7 @@ const BashToolBase = defineTool({
 function commandFacts(input: {
 	command: string
 	exitCode?: number
+	exitNote?: string
 	timedOut?: boolean
 	signal?: string
 	stdout: string
@@ -867,6 +882,7 @@ function commandFacts(input: {
 		kind: 'command',
 		command: input.command,
 		...(input.exitCode !== undefined ? { exitCode: input.exitCode } : {}),
+		...(input.exitNote ? { exitNote: input.exitNote } : {}),
 		...(input.timedOut ? { timedOut: true } : {}),
 		...(input.signal ? { signal: input.signal } : {}),
 		...(input.stdout && !outBinary ? { stdout: windowText(input.stdout, outBytes) } : {}),

package/src/tools/builtins/edit-apply.ts

@@ -130,6 +130,13 @@ function normalizeInsertLine(
 	return { success: true, value }
 }
 
+/** A refused edit, with the kind of refusal when it is one a host can phrase. */
+export type EditApplyFailure = {
+	success: false
+	error: string
+	reason?: 'text_not_found' | 'not_unique'
+}
+
 /**
  * Apply every operation in order, or none of them.
  *
@@ -149,7 +156,7 @@ function normalizeInsertLine(
 export function applyEdit(
 	content: string,
 	operations: readonly NormalizedEditInput[],
-): { success: true; content: string; replacements: number } | { success: false; error: string } {
+): { success: true; content: string; replacements: number } | EditApplyFailure {
 	let current = content
 	let replacements = 0
 
@@ -159,6 +166,7 @@ export function applyEdit(
 			return {
 				success: false,
 				error: framedError(result.error, index, operations.length),
+				...(result.reason ? { reason: result.reason } : {}),
 			}
 		}
 		current = result.content
@@ -171,7 +179,7 @@ export function applyEdit(
 function applyOne(
 	content: string,
 	input: NormalizedEditInput,
-): { success: true; content: string; replacements: number } | { success: false; error: string } {
+): { success: true; content: string; replacements: number } | EditApplyFailure {
 	if (input.operation === 'insert') {
 		return applyLineInsert(content, input)
 	}
@@ -191,6 +199,7 @@ function applyOne(
 		if (resolved === null) {
 			return {
 				success: false,
+				reason: 'text_not_found',
 				error:
 					'old_string/oldStr not found in file. Make sure the string matches exactly, including whitespace and indentation.',
 			}
@@ -225,6 +234,7 @@ function applyOne(
 		const secondLine = content.slice(0, secondIndex).split('\n').length
 		return {
 			success: false,
+			reason: 'not_unique',
 			error: `old_string/oldStr is not unique — found at lines ${lineNumber} and ${secondLine}. Provide more surrounding context to make it unique, or use replace_all: true.`,
 		}
 	}

package/src/tools/builtins/edit.ts

@@ -2,12 +2,18 @@ import { readFile } from 'node:fs/promises'
 
 import { z } from 'zod'
 import type { ToolContext, ToolResult } from '../../types/tool/index.js'
+import type { ToolFacts } from '../../types/tool/presentation.js'
 import { defineTool } from '../defineTool.js'
 import { resolveWithinAnyReal, toolRoots } from '../paths.js'
 import { atomicWriteFile } from './atomic-write-file.js'
 import { clip, describeChange } from './classifier-input.js'
 import { fingerprintContent, staleFileError, unreadFileError } from './content-fingerprint.js'
-import { type NormalizedEditInput, applyEdit, normalizeEditInput } from './edit-apply.js'
+import {
+	type EditApplyFailure,
+	type NormalizedEditInput,
+	applyEdit,
+	normalizeEditInput,
+} from './edit-apply.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
 import { jsonStringEscapes } from './json-string-hint.js'
 import { lineDiff } from './line-diff.js'
@@ -334,7 +340,7 @@ function recordDrift(context: ToolContext, key: string): void {
 }
 
 type EditAdmission =
-	| { success: false; output: ''; error: string }
+	| { success: false; output: ''; error: string; facts: ToolFacts }
 	| { success: true; result: ReturnType<typeof applyEdit> }
 
 /**
@@ -359,7 +365,12 @@ function admitAgainstRead(
 ): EditAdmission {
 	const tracker = context.fileReadTracker
 	if (tracker && !tracker.hasRead(key)) {
-		return { success: false, output: '', error: unreadFileError(key, 'edit') }
+		return {
+			success: false,
+			output: '',
+			error: unreadFileError(key, 'edit'),
+			facts: { kind: 'failure', reason: 'not_read', subject: key },
+		}
 	}
 	const seen = tracker?.fingerprint?.(key)
 	const applied = applyEdit(content, operations)
@@ -367,7 +378,12 @@ function admitAgainstRead(
 		const recoverable = applied.success && operations.every((o) => o.operation === 'replace')
 		if (!recoverable) {
 			recordDrift(context, key)
-			return { success: false, output: '', error: staleFileError(key) }
+			return {
+				success: false,
+				output: '',
+				error: staleFileError(key),
+				facts: { kind: 'failure', reason: 'changed_on_disk', subject: key },
+			}
 		}
 	}
 	return { success: true, result: applied }
@@ -397,6 +413,18 @@ function editFacts(path: string, replacements: number, before: string, after: st
 	}
 }
 
+/** A refused edit, with the kind of refusal when the text said it. */
+function refusedEdit(result: EditApplyFailure, path: string) {
+	return {
+		success: false as const,
+		output: '' as const,
+		error: result.error,
+		...(result.reason
+			? { facts: { kind: 'failure' as const, reason: result.reason, subject: path } }
+			: {}),
+	}
+}
+
 export const EditTool = defineTool({
 	name: 'edit',
 	description:
@@ -529,9 +557,7 @@ export const EditTool = defineTool({
 				const admitted = admitAgainstRead(context, parsed.data.path, content, normalized.operations)
 				if (!admitted.success) return admitted
 				const result = admitted.result
-				if (!result.success) {
-					return { success: false as const, output: '', error: result.error }
-				}
+				if (!result.success) return refusedEdit(result, parsed.data.path)
 
 				await context.sandbox.writeFile(parsed.data.path, result.content)
 				recordEditedContent(context, parsed.data.path, result.content)
@@ -554,7 +580,7 @@ export const EditTool = defineTool({
 			const admitted = admitAgainstRead(context, hostPath, content, normalized.operations)
 			if (!admitted.success) return admitted
 			const result = admitted.result
-			if (!result.success) return { success: false as const, output: '', error: result.error }
+			if (!result.success) return refusedEdit(result, hostPath)
 
 			// Temp file, fsync, rename — a reader sees the old body or the new
 			// one, never a half-written one. A plain `writeFile` that fails

package/src/tools/builtins/exit-semantics.ts

@@ -0,0 +1,198 @@
+/**
+ * How a shell command's exit code is judged.
+ *
+ * Some programs use a non-zero status to answer a question rather than to
+ * report a failure: `grep` exits 1 when nothing matched, `diff` exits 1 when
+ * the files differ, `test` exits 1 when the condition is false. Reading those
+ * as failures turns a normal answer into a red error and sends the model off
+ * to "fix" it. Every other command keeps the plain rule: non-zero is a failure.
+ *
+ * The command is judged by the last command on its line (the one whose status
+ * the shell reports), but only when nothing earlier in an `&&` chain could
+ * have supplied that status: after `cd missing && grep x f` a 1 may come from
+ * `cd`, so the line is judged by the plain rule.
+ */
+
+/** What an exit code means for one command line. */
+export interface ExitJudgement {
+	/** The command failed. */
+	readonly isError: boolean
+	/** A short plain sentence for a non-zero status that is not a failure. */
+	readonly note?: string
+}
+
+/** Longest line the splitter reads; a longer one gets the plain rule. */
+const MAX_COMMAND_CHARS = 10_000
+
+const PLAIN_FAILURE: ExitJudgement = { isError: true }
+
+interface Parsed {
+	/** Command texts in order, with the separator that preceded each. */
+	readonly segments: readonly string[]
+	readonly separators: readonly string[]
+}
+
+/**
+ * Cut a line at unquoted `|`, `|&`, `||`, `&&`, `;`, `&` and newlines.
+ * Undefined when the line has a shape this reading does not follow (an open
+ * quote, a subshell or group, a here-document): the caller then keeps the
+ * plain rule, which is the safe reading.
+ */
+function split(command: string): Parsed | undefined {
+	const segments: string[] = []
+	const separators: string[] = []
+	let current = ''
+	let pending = ''
+	let quote: '"' | "'" | null = null
+	const push = (): void => {
+		segments.push(current)
+		separators.push(pending)
+		current = ''
+	}
+	for (let i = 0; i < command.length; i++) {
+		const ch = command.charAt(i)
+		const next = command.charAt(i + 1)
+		if (quote === "'") {
+			if (ch === "'") quote = null
+			current += ch
+			continue
+		}
+		if (ch === '\\') {
+			current += ch + next
+			i += 1
+			continue
+		}
+		if (ch === '`') {
+			const end = command.indexOf('`', i + 1)
+			if (end === -1) return undefined
+			current += command.slice(i, end + 1)
+			i = end
+			continue
+		}
+		if (ch === '$' && (next === '(' || next === '{')) {
+			const close = next === '(' ? ')' : '}'
+			let depth = 0
+			let j = i + 1
+			for (; j < command.length; j++) {
+				const c = command.charAt(j)
+				if (c === next) depth += 1
+				else if (c === close && --depth === 0) break
+			}
+			if (j >= command.length) return undefined
+			current += command.slice(i, j + 1)
+			i = j
+			continue
+		}
+		if (quote === '"') {
+			if (ch === '"') quote = null
+			current += ch
+			continue
+		}
+		if (ch === '"' || ch === "'") {
+			quote = ch
+			current += ch
+			continue
+		}
+		if (ch === '(' || ch === ')') return undefined
+		if (ch === '<' && next === '<' && command.charAt(i + 2) !== '<') return undefined
+		if (ch === '>' && next === '&') {
+			// `2>&1` and `>&2` are redirects, not a background `&`.
+			current += ch + next
+			i += 1
+			continue
+		}
+		if (ch === '&' && command.charAt(i - 1) === '>') {
+			current += ch
+			continue
+		}
+		if (ch === '|' || ch === '&' || ch === ';' || ch === '\n') {
+			let sep = ch
+			if ((ch === '|' || ch === '&') && next === ch) {
+				sep = ch + ch
+				i += 1
+			} else if (ch === '|' && next === '&') {
+				sep = '|&'
+				i += 1
+			}
+			push()
+			pending = sep === '\n' ? ';' : sep
+			continue
+		}
+		current += ch
+	}
+	if (quote !== null) return undefined
+	push()
+	// A trailing separator (`a;`) leaves an empty last segment: drop it.
+	const kept: string[] = []
+	const keptSeparators: string[] = []
+	segments.forEach((segment, index) => {
+		if (segment.trim().length === 0) return
+		kept.push(segment.trim())
+		keptSeparators.push(separators[index] ?? '')
+	})
+	return kept.length === 0 ? undefined : { segments: kept, separators: keptSeparators }
+}
+
+/**
+ * Whether an earlier command in an `&&` chain could be the one whose status
+ * the line ended with: the last pipeline is joined to what precedes it by `&&`.
+ */
+function followsAndChain(parsed: Parsed): boolean {
+	let index = parsed.segments.length - 1
+	// Walk back over the pipeline the last command belongs to.
+	while (index > 0 && (parsed.separators[index] === '|' || parsed.separators[index] === '|&')) {
+		index -= 1
+	}
+	return parsed.separators[index] === '&&'
+}
+
+const NO_MATCHES = 'No matches found'
+
+const SEARCH_WORDS = new Set(['grep', 'rg', 'egrep', 'fgrep'])
+
+/** The subcommand of a `git` line, skipping global options (`-C <dir>`, `-c <k=v>`). */
+function gitSubcommand(words: readonly string[]): string | undefined {
+	if (words[0] !== 'git') return undefined
+	for (let i = 1; i < words.length; i++) {
+		const word = words[i] as string
+		if (word.startsWith('-')) {
+			if (word === '-C' || word === '-c') i += 1
+			continue
+		}
+		return word
+	}
+	return undefined
+}
+
+function questionNote(command: string): string | undefined {
+	const words = command.trim().split(/\s+/)
+	const first = words[0] ?? ''
+	if (first === 'git') {
+		const sub = gitSubcommand(words)
+		if (sub === 'diff') return 'Files differ'
+		if (sub === 'grep') return NO_MATCHES
+		return undefined
+	}
+	if (SEARCH_WORDS.has(first)) return NO_MATCHES
+	if (first === 'find') return 'Some directories were inaccessible'
+	if (first === 'diff') return 'Files differ'
+	if (first === 'test' || first === '[') return 'Condition is false'
+	return undefined
+}
+
+/**
+ * Judge a finished command's exit code.
+ *
+ * Exit 0 is never a failure. For `grep`, `rg`, `egrep`, `fgrep`, `find`,
+ * `diff`, `test`, `[`, `git diff` and `git grep` as the last command of the
+ * line, exit 1 is an answer (with a short note) and 2 or more is a failure.
+ * Anything else, or a line the reading cannot follow, fails on any non-zero.
+ */
+export function judgeExit(command: string, exitCode: number): ExitJudgement {
+	if (exitCode === 0) return { isError: false }
+	if (exitCode !== 1 || command.length > MAX_COMMAND_CHARS) return PLAIN_FAILURE
+	const parsed = split(command)
+	if (!parsed || followsAndChain(parsed)) return PLAIN_FAILURE
+	const note = questionNote(parsed.segments[parsed.segments.length - 1] as string)
+	return note === undefined ? PLAIN_FAILURE : { isError: false, note }
+}

package/src/tools/builtins/write-file.ts

@@ -210,7 +210,7 @@ function enforceReadBeforeOverwrite(
 		success: false,
 		output: '',
 		error: `${key} already exists. Use the \`read\` tool on it first in this conversation, then call \`write\` again — or prefer \`edit\` for a targeted change.`,
-		facts: { kind: 'failure', reason: 'already_exists', subject: key },
+		facts: { kind: 'failure', reason: 'not_read', subject: key },
 	}
 }
 
@@ -232,7 +232,12 @@ function enforceFreshOverwrite(
 		// so a reader that cannot touch the filesystem stops referencing this
 		// path. Optional on the interface; an older tracker keeps its behavior.
 		context.fileReadTracker?.recordDriftObserved?.(key)
-		return { success: false, output: '', error: staleFileError(key, 'write') }
+		return {
+			success: false,
+			output: '',
+			error: staleFileError(key, 'write'),
+			facts: { kind: 'failure', reason: 'changed_on_disk', subject: key },
+		}
 	}
 	return null
 }

package/src/tools/memory/delete.ts

@@ -10,7 +10,7 @@ export function buildDeleteMemoryTool(store: MemoryStore): ToolDefinition {
 	return defineTool({
 		name: 'delete_memory',
 		description:
-			'Permanently delete a stored memory by ID. Use update_memory with status archived when the record should remain available for inspection. Deletion does not erase past conversation transcripts. Pass the revision from read_memory when available to refuse a stale deletion.',
+			'Permanently remove a memory by ID, for one that should not be kept at all. Use update_memory with status archived when the record should stay available to inspect. Past conversation transcripts are not changed. Pass the revision from read_memory when available, so a deletion of a memory that changed since you read it is refused. Returns a confirmation.',
 		inputSchema: z.object({
 			id: z.string().describe('Memory ID to permanently delete'),
 			revision: z

package/src/tools/memory/read.ts

@@ -16,7 +16,7 @@ export function buildReadMemoryTool(store: MemoryStore): ToolDefinition {
 	return defineTool({
 		name: 'read_memory',
 		description:
-			'Read the full content of a specific memory by its ID or its name. For a text or Markdown memory the result ends with how old the memory is and resolves any [[name]] links it contains.',
+			'Read one memory in full by its ID or its name. Use it when the index or a search shows that a memory bears on the task. Returns the memory text; a text or Markdown memory ends with how old it is and the memories its [[name]] links point to.',
 		inputSchema: z.object({
 			id: z
 				.string()

package/src/tools/memory/save.ts

@@ -10,11 +10,12 @@ export function buildSaveMemoryTool(store: MemoryStore): ToolDefinition {
 	return defineTool({
 		name: 'save_memory',
 		description: [
-			'Save a new memory for future sessions: something true now that a later session could not work out from the code, the git history or the files themselves. Do not save what those already say.',
-			'Choose a type: user (who the user is and how they like to work), feedback (a rule the user gave about how to work), project (a fact or decision about the work), reference (where to look for something).',
+			'Save one memory for later sessions in this project: a single fact that the code, the history and the docs do not already hold.',
+			'Choose a type: user (who the person is and how they like to work), feedback (a rule they gave about how to work), project (a fact or decision about the work), reference (where to look for something).',
 			'For feedback and project memories, write the rule or fact first, then a line starting "Why:" and a line starting "How to apply:".',
 			'Link a related memory by writing [[its-name]] in the content.',
-			'If a memory on this already exists, use update_memory instead: a name another memory holds is refused.',
+			'The name must be new: a name another memory holds is refused, and the reply points to update_memory.',
+			"Returns the saved memory's id and name.",
 		].join(' '),
 		inputSchema: z.object({
 			title: z.string().min(1).describe('Short descriptive title'),

package/src/tools/memory/search.ts

@@ -16,7 +16,7 @@ function defineSearchMemoryTool(search: SearchMemory): ToolDefinition {
 	return defineTool({
 		name: 'search_memory',
 		description:
-			'Search active stored memories by relevant words or tags. The built-in stores rank matches in names, titles, descriptions, summaries and full content. Built-in search examines at most 256 recent candidates per call; if incomplete, continue with the returned scan_offset. Use read_memory for evidence. Set status to archived to inspect obsolete records.',
+			"Find stored memories by words or tags. Use it when the topic is not in the index, before saving (to see whether a memory already covers it), and to reach what earlier turns recorded on their own. Matches are ranked across names, titles, descriptions, summaries and content; one call examines at most 256 recent candidates, and an incomplete result returns a scan_offset to continue from. Set status to archived to look at retired memories. Returns a numbered list with each memory's id, title, type and description; open one with read_memory.",
 		inputSchema: z.object({
 			query: z.string().optional().describe('Relevant words or identifiers to search'),
 			tags: z.array(z.string()).optional().describe('Filter by tags (all must match)'),

package/src/tools/memory/update.ts

@@ -12,7 +12,7 @@ export function buildUpdateMemoryTool(store: MemoryStore): ToolDefinition {
 	return defineTool({
 		name: 'update_memory',
 		description:
-			'Correct an existing memory in place, or archive an obsolete claim so it is no longer recalled. Prefer this to saving a second memory about the same thing. Identify it by the ID from search_memory or by its name from the memory index; current evidence should determine corrections. Pass the revision from read_memory when available to refuse a stale correction.',
+			'Correct a memory in place, or archive one that is no longer true so it stops being recalled. Use it when a memory on the same topic already exists, which keeps the store free of duplicates, and when current evidence shows a memory is wrong. Identify the memory by the ID from search_memory or by its name from the index. Pass the revision from read_memory when available, so a change made since you read it is refused instead of overwritten. Returns the memory as it now stands.',
 		inputSchema: z.object({
 			id: z
 				.string()

package/src/toolsets/manager.ts

@@ -1012,7 +1012,12 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 			'namzu.registry.errors': errorMessage,
 			'namzu.registry.empty': isEmptyInput,
 		})
-		return { success: false, output: '', error: enrichedMessage }
+		return {
+			success: false,
+			output: '',
+			error: enrichedMessage,
+			facts: { kind: 'failure', reason: 'invalid_arguments' },
+		}
 	}
 }
 

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),