@namzu/sdk 53.2.1 → 54.0.0

package/dist/types/tool/presentation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"presentation.d.ts","sourceRoot":"","sources":["../../../src/types/tool/presentation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"presentation.d.ts","sourceRoot":"","sources":["../../../src/types/tool/presentation.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "53.2.1",
+  "version": "54.0.0",
   "description": "Open-source AI kernel for TypeScript: runs an agent the way an operating system runs a process, with an identity and a budget, scheduled tool calls and checkpointed turns.",
   "license": "FSL-1.1-MIT",
   "engines": {

package/src/compaction/context-breakdown.ts

@@ -0,0 +1,228 @@
+/**
+ * Where the context window goes: the arithmetic behind a `/context` view.
+ *
+ * Pure. A host hands in what it knows (sizes of the system prompt, the tool
+ * catalogue, instruction files, skills, agents, and the conversation) and gets
+ * the categories back in the order they are drawn, with the free room and the
+ * compaction buffer accounted for. Nothing here reads a provider or a file.
+ *
+ * The conversation's own share is never counted separately: it is whatever the
+ * measured prompt size is once the fixed parts are taken out, so the categories
+ * always add up to the figure the provider reported.
+ */
+
+import { CHARS_PER_TOKEN } from '../constants/limits.js'
+import type { Message } from '../types/message/index.js'
+import type { LLMToolSchema } from '../types/tool/index.js'
+import { TRIGGER_BUFFER_TOKENS, TRIGGER_OUTPUT_RESERVE_CAP_TOKENS } from './context-window.js'
+import { estimateMessageTokens, estimateTextTokens } from './token-estimate.js'
+
+/** The categories, in the order they are laid out. */
+export const CONTEXT_CATEGORY_ORDER = [
+	'system-prompt',
+	'system-tools',
+	'mcp-tools',
+	'mcp-instructions',
+	'agents',
+	'memory',
+	'skills',
+	'messages',
+] as const
+
+export type ContextCategoryId = (typeof CONTEXT_CATEGORY_ORDER)[number] | 'buffer' | 'free'
+export type ContextCategoryKind = 'used' | 'free' | 'buffer'
+
+export interface ContextCategory {
+	readonly id: ContextCategoryId
+	readonly name: string
+	readonly tokens: number
+	readonly kind: ContextCategoryKind
+}
+
+const NAMES: Record<(typeof CONTEXT_CATEGORY_ORDER)[number], string> = {
+	'system-prompt': 'System prompt',
+	'system-tools': 'System tools',
+	'mcp-tools': 'MCP tools',
+	'mcp-instructions': 'MCP server instructions',
+	agents: 'Custom agents',
+	memory: 'Memory files',
+	skills: 'Skills',
+	messages: 'Messages',
+}
+
+export interface ContextUsageInput {
+	readonly windowTokens: number
+	/**
+	 * `auto` when the window is what the provider or model table declares.
+	 * Anything else (`config`, `default`) means the figure was overridden or
+	 * guessed, and the compaction buffer is then drawn.
+	 */
+	readonly windowSource: 'auto' | 'config' | 'default'
+	/** What the model may write in one reply; absent reserves the full cap. */
+	readonly maxOutputTokens?: number
+	/** Whether the session summarises on its own. */
+	readonly autoCompact: boolean
+	/**
+	 * The size of everything being sent: counted by the provider, or estimated.
+	 * Absent, the conversation is estimated from `messages`.
+	 */
+	readonly contextTokens?: number
+	readonly systemPromptTokens?: number
+	/** Tokens of the built-in tool definitions. */
+	readonly systemToolTokens?: number
+	readonly mcpToolTokens?: number
+	readonly mcpInstructionTokens?: number
+	readonly agentTokens?: number
+	readonly memoryTokens?: number
+	readonly skillTokens?: number
+	/** The conversation, for the estimate and for the per-tool breakdown. */
+	readonly messages?: readonly Message[]
+}
+
+export interface ContextMessageBreakdown {
+	/** Tokens of the calls the model wrote, by tool name. */
+	readonly toolCallsByType: Readonly<Record<string, number>>
+	/** Tokens of the results that came back, by the name of the tool called. */
+	readonly toolResultsByType: Readonly<Record<string, number>>
+	readonly assistantTokens: number
+	readonly userTokens: number
+}
+
+export interface ContextBreakdown {
+	readonly categories: readonly ContextCategory[]
+	readonly windowTokens: number
+	/** Everything in use, which can exceed the window. */
+	readonly totalTokens: number
+	/** Whole percent of the window in use. */
+	readonly percentage: number
+	/** The compaction buffer, 0 when it is not drawn. */
+	readonly bufferTokens: number
+	/** Whether the session summarises on its own; names the buffer. */
+	readonly autoCompact: boolean
+	/** How far past the window the context is; 0 while it fits. */
+	readonly overflowTokens: number
+	readonly messageBreakdown: ContextMessageBreakdown
+}
+
+/** Per-tool size of a catalogue already rendered the way it is sent. */
+export function describeToolCatalogTokens(
+	tools: readonly LLMToolSchema[],
+): { name: string; tokens: number }[] {
+	return tools.map((tool) => {
+		let length = 0
+		try {
+			length = JSON.stringify(tool).length
+		} catch {
+			// A tool that cannot render is the model call's problem to report.
+		}
+		return { name: tool.function.name, tokens: Math.ceil(length / CHARS_PER_TOKEN) }
+	})
+}
+
+function nonNegative(value: number | undefined): number {
+	return value !== undefined && Number.isFinite(value) && value > 0 ? Math.round(value) : 0
+}
+
+function bufferFor(input: ContextUsageInput): number {
+	if (input.autoCompact) {
+		// Drawn only when the window was overridden: on a declared window the
+		// room kept for a reply is not a thing the person chose.
+		if (input.windowSource === 'auto') return 0
+		const reserve = Math.min(
+			input.maxOutputTokens !== undefined && input.maxOutputTokens > 0
+				? input.maxOutputTokens
+				: TRIGGER_OUTPUT_RESERVE_CAP_TOKENS,
+			TRIGGER_OUTPUT_RESERVE_CAP_TOKENS,
+		)
+		return reserve + TRIGGER_BUFFER_TOKENS
+	}
+	return COMPACT_BUFFER_TOKENS
+}
+
+/** Room kept for a manual compaction when nothing summarises on its own. */
+export const COMPACT_BUFFER_TOKENS = 3_000
+
+function tokensOfContent(message: Message): number {
+	return estimateMessageTokens(message)
+}
+
+function breakdownMessages(messages: readonly Message[]): ContextMessageBreakdown {
+	const toolCallsByType: Record<string, number> = {}
+	const toolResultsByType: Record<string, number> = {}
+	const nameOfCall = new Map<string, string>()
+	let assistantTokens = 0
+	let userTokens = 0
+	for (const message of messages) {
+		if (message.role === 'assistant') {
+			let calls = 0
+			for (const call of message.toolCalls ?? []) {
+				nameOfCall.set(call.id, call.function.name)
+				const tokens = estimateTextTokens(call.function.name + call.function.arguments)
+				toolCallsByType[call.function.name] = (toolCallsByType[call.function.name] ?? 0) + tokens
+				calls += tokens
+			}
+			assistantTokens += Math.max(0, tokensOfContent(message) - calls)
+		} else if (message.role === 'tool') {
+			const name = nameOfCall.get(message.toolCallId) ?? 'unknown'
+			toolResultsByType[name] = (toolResultsByType[name] ?? 0) + tokensOfContent(message)
+		} else if (message.role === 'user') {
+			userTokens += tokensOfContent(message)
+		}
+	}
+	return { toolCallsByType, toolResultsByType, assistantTokens, userTokens }
+}
+
+/** Split a window into the parts that fill it. */
+export function analyzeContextUsage(input: ContextUsageInput): ContextBreakdown {
+	const windowTokens = Math.max(0, Math.round(input.windowTokens))
+	const fixed: Record<(typeof CONTEXT_CATEGORY_ORDER)[number], number> = {
+		'system-prompt': nonNegative(input.systemPromptTokens),
+		'system-tools': nonNegative(input.systemToolTokens),
+		'mcp-tools': nonNegative(input.mcpToolTokens),
+		'mcp-instructions': nonNegative(input.mcpInstructionTokens),
+		agents: nonNegative(input.agentTokens),
+		memory: nonNegative(input.memoryTokens),
+		skills: nonNegative(input.skillTokens),
+		messages: 0,
+	}
+	const fixedTotal = Object.values(fixed).reduce((sum, tokens) => sum + tokens, 0)
+	const messages = input.messages ?? []
+	const bufferTokens = Math.min(bufferFor(input), windowTokens)
+
+	// The conversation is what the measured size leaves once the fixed parts
+	// are taken out; without a measurement it is counted from the messages.
+	const measured = nonNegative(input.contextTokens)
+	const rawMessages =
+		measured > 0
+			? Math.max(0, measured - fixedTotal)
+			: messages.reduce((sum, message) => sum + tokensOfContent(message), 0)
+	fixed.messages = Math.min(rawMessages, Math.max(0, windowTokens - fixedTotal - bufferTokens))
+
+	const totalTokens = measured > 0 ? Math.max(measured, fixedTotal) : fixedTotal + rawMessages
+	const used = fixedTotal + fixed.messages
+	const categories: ContextCategory[] = []
+	for (const id of CONTEXT_CATEGORY_ORDER) {
+		if (fixed[id] > 0) categories.push({ id, name: NAMES[id], tokens: fixed[id], kind: 'used' })
+	}
+	const free = Math.max(0, windowTokens - used - bufferTokens)
+	if (bufferTokens > 0) {
+		categories.push({
+			id: 'buffer',
+			name: input.autoCompact ? 'Autocompact buffer' : 'Compact buffer',
+			tokens: bufferTokens,
+			kind: 'buffer',
+		})
+	}
+	categories.push({ id: 'free', name: 'Free space', tokens: free, kind: 'free' })
+
+	return {
+		categories,
+		windowTokens,
+		totalTokens,
+		percentage: windowTokens > 0 ? Math.round((totalTokens / windowTokens) * 100) : 0,
+		bufferTokens,
+		autoCompact: input.autoCompact,
+		overflowTokens: Math.max(0, totalTokens - windowTokens),
+		messageBreakdown: breakdownMessages(messages),
+	}
+}

package/src/compaction/token-estimate.ts

@@ -52,6 +52,11 @@ export function estimateMessageTokens(message: Message): number {
 	return Math.ceil(chars / CHARS_PER_TOKEN) + rich
 }
 
+/** Tokens in a piece of text by the same characters-per-token approximation. */
+export function estimateTextTokens(text: string): number {
+	return Math.ceil(text.length / CHARS_PER_TOKEN)
+}
+
 export function estimateMessagesTokens(messages: readonly Message[]): number {
 	return messages.reduce((total, message) => total + estimateMessageTokens(message), 0)
 }

package/src/public-runtime.ts

@@ -404,8 +404,13 @@ export type {
 // session between turns.
 export { abandonTurn } from './runtime/query/abandon-turn.js'
 export type { AbandonTurnOptions, SessionLocatorOptions } from './runtime/query/abandon-turn.js'
-export { compactSession } from './runtime/query/compact-session.js'
-export type { CompactSessionParams } from './runtime/query/compact-session.js'
+export { CacheClock } from './runtime/cache-clock.js'
+export type { CacheClockState } from './runtime/cache-clock.js'
+export { compactSession, compactSessionRange } from './runtime/query/compact-session.js'
+export type {
+	CompactSessionParams,
+	CompactSessionRangeParams,
+} from './runtime/query/compact-session.js'
 export { prepareForkState } from './runtime/query/fork/prepare.js'
 export { listCheckpoints } from './runtime/query/fork/list.js'
 export { DecisionParser, FallbackResolver } from './runtime/decision/index.js'
@@ -1563,6 +1568,22 @@ export {
 // The gate is the reason this is a list rather than a fourth accident.
 export type { ResolvedContextWindow } from './compaction/context-window.js'
 export { resolveTriggerThreshold } from './compaction/context-window.js'
+// What the context window is made of, for a host that draws the answer to
+// "where did my context go".
+export {
+	analyzeContextUsage,
+	describeToolCatalogTokens,
+	CONTEXT_CATEGORY_ORDER,
+} from './compaction/context-breakdown.js'
+export type {
+	ContextBreakdown,
+	ContextCategory,
+	ContextCategoryId,
+	ContextCategoryKind,
+	ContextMessageBreakdown,
+	ContextUsageInput,
+} from './compaction/context-breakdown.js'
+export { estimateTextTokens } from './compaction/token-estimate.js'
 export type { CompactRegionInput } from './compaction/manual.js'
 export type {
 	CompactionVerificationOptions,

package/src/runtime/cache-clock.ts

@@ -0,0 +1,67 @@
+import type { TokenUsage } from '../types/common/index.js'
+
+/** What the clock knows about the prompt cache after the latest model call. */
+export interface CacheClockState {
+	/** When the last call that touched the cache finished (ms since epoch). */
+	readonly lastActivityAt: number
+	/** How long the provider keeps the cache, as that call reported it. */
+	readonly ttlMs: number
+	/**
+	 * When the cache lapses: `lastActivityAt + ttlMs`. Only set when the call
+	 * actually read or wrote cache; a call that touched none leaves the cache
+	 * (and so its expiry) unknown rather than assumed.
+	 */
+	readonly expiresAt: number | null
+}
+
+/**
+ * Tracks when a conversation's prompt cache will lapse.
+ *
+ * Fed by each completed model call. The lifetime is never guessed: a call whose
+ * usage carries no `cacheTtlMs` (a driver that does not report one) clears the
+ * clock, so nothing downstream can act on a lifetime nobody stated. Pure of
+ * timers: the caller passes `now`.
+ */
+export class CacheClock {
+	#state: CacheClockState | null = null
+
+	/** Record a finished call. `usage` is that call's own usage, not a turn total. */
+	record(usage: TokenUsage, at: number): void {
+		if (usage.cacheTtlMs === undefined || !(usage.cacheTtlMs > 0)) {
+			this.#state = null
+			return
+		}
+		const touched = usage.cachedTokens + usage.cacheWriteTokens > 0
+		this.#state = {
+			lastActivityAt: at,
+			ttlMs: usage.cacheTtlMs,
+			expiresAt: touched ? at + usage.cacheTtlMs : null,
+		}
+	}
+
+	/** Forget everything (the conversation was replaced or its context rewritten). */
+	reset(): void {
+		this.#state = null
+	}
+
+	get state(): CacheClockState | null {
+		return this.#state
+	}
+
+	/** Whether the cache is still alive at `now`. False when unknown. */
+	warm(now: number): boolean {
+		const state = this.#state
+		return state !== null && state.expiresAt !== null && now < state.expiresAt
+	}
+
+	/**
+	 * The moment `fraction` of the cache's remaining life since the last
+	 * activity has passed: `lastActivityAt + (expiresAt - lastActivityAt) * fraction`.
+	 * `null` when the expiry is unknown.
+	 */
+	dueAt(fraction: number): number | null {
+		const state = this.#state
+		if (state === null || state.expiresAt === null) return null
+		return state.lastActivityAt + (state.expiresAt - state.lastActivityAt) * fraction
+	}
+}

package/src/runtime/query/compact-session.ts

@@ -1,4 +1,9 @@
-import { type CompactNowInput, type CompactionResult, compactNow } from '../../compaction/manual.js'
+import {
+	type CompactNowInput,
+	type CompactionResult,
+	compactNow,
+	compactRegion,
+} from '../../compaction/manual.js'
 import { readFoldedHistory } from '../../manager/session/turn-recorder.js'
 import { NamzuError } from '../../types/errors/index.js'
 import type { MessageId, SessionId } from '../../types/ids/index.js'
@@ -10,13 +15,19 @@ import { type SessionLocatorOptions, locateSessionLog, withSessionLease } from '
 /** A compaction a host asks for between turns. */
 export interface CompactSessionParams extends Omit<CompactNowInput, 'messages' | 'onShed'> {
 	readonly sessionId: SessionId
+	/**
+	 * Who asked. `'manual'` (the default) is a person's request; `'idle'` is a
+	 * host compacting a conversation nobody is using before its prompt cache
+	 * lapses. Recorded on the `compaction` record.
+	 */
+	readonly trigger?: 'manual' | 'idle'
 	/** Where to find the session's log, and the lease to append under. */
 	readonly locator?: SessionLocatorOptions
 }
 
 /**
  * Compact a session outside any turn. Reads the session's context from its
- * log, compacts it, and appends a `compaction{ trigger: 'manual' }` record
+ * log, compacts it, and appends a `compaction{ trigger }` record (`'manual'` unless the host says `'idle'`)
  * with no `turnId`: the messages the pass kept are named by id, the summary
  * is recorded in full, and the shed messages stay in the log for audit.
  *
@@ -26,7 +37,7 @@ export interface CompactSessionParams extends Omit<CompactNowInput, 'messages' |
 export async function compactSession(
 	params: CompactSessionParams,
 ): Promise<CompactionResult | null> {
-	const { sessionId, locator = {}, ...input } = params
+	const { sessionId, locator = {}, trigger = 'manual', ...input } = params
 	const log = await locateSessionLog(sessionId, locator)
 	return withSessionLease(log, locator.lease, async (lease) => {
 		const active = await log.activeTurn({ lease })
@@ -47,6 +58,93 @@ export async function compactSession(
 			})
 		}
 		const { summary, keptMessageIds } = compactionShape(result.messages, ids)
+		await log.append(lease, {
+			type: 'compaction',
+			compactionId: generateMessageId(),
+			strategy: input.config.strategy,
+			trigger,
+			replacesSeqRange: [1, head.pointer.seq],
+			summary,
+			keptMessageIds,
+			tokensBefore: 0,
+			tokensAfter: 0,
+		})
+		return result
+	})
+}
+
+/** A compaction of one span of a session's context, asked for between turns. */
+export interface CompactSessionRangeParams extends CompactSessionParams {
+	/**
+	 * The first message to summarise, by the id the log recorded it under.
+	 * Omitted: the span starts at the beginning of the context.
+	 */
+	readonly from?: MessageId
+	/**
+	 * The message the span stops before; it and everything after it stay as
+	 * they are. Omitted: the span runs to the end of the context.
+	 */
+	readonly until?: MessageId
+}
+
+/**
+ * Compact one span of a session's context outside any turn.
+ *
+ * Like {@link compactSession}, but only the messages from `from` up to (not
+ * including) `until` are summarised; the rest of the context stays verbatim.
+ * A host uses it to fold away "everything before this message" or "this
+ * message and everything after it" without touching the other side. Pinned
+ * (`retain`) messages inside the span stay as they are.
+ *
+ * Throws `not_found` when `from` or `until` is not in the session's current
+ * context (a compaction may already have folded it away), and
+ * `invalid_config` when a boundary would split a tool call from its result.
+ * `null` when the span holds nothing worth summarising; nothing is appended
+ * then. Refused while a turn is active (`TurnInProgressError`).
+ */
+export async function compactSessionRange(
+	params: CompactSessionRangeParams,
+): Promise<CompactionResult | null> {
+	const { sessionId, locator = {}, from, until, ...input } = params
+	const log = await locateSessionLog(sessionId, locator)
+	return withSessionLease(log, locator.lease, async (lease) => {
+		const active = await log.activeTurn({ lease })
+		if (active) {
+			throw new TurnInProgressError({ sessionId, activeTurnId: active.turnId, state: active.state })
+		}
+		const history = await readFoldedHistory(log)
+		const position = (id: MessageId | undefined, fallback: number): number => {
+			if (id === undefined) return fallback
+			const at = history.findIndex((entry) => entry.messageId === id)
+			if (at < 0) {
+				throw new NamzuError({
+					code: 'not_found',
+					message: `Message ${id} is not in session ${sessionId}'s current context; it may already have been summarised.`,
+					details: { sessionId, messageId: id },
+				})
+			}
+			return at
+		}
+		const start = position(from, 0)
+		const end = position(until, history.length)
+		const ids = new Map<Message, MessageId>()
+		for (const entry of history) if (entry.messageId) ids.set(entry.message, entry.messageId)
+		const result = await compactRegion({
+			...input,
+			messages: history.map((entry) => entry.message),
+			start,
+			end,
+		})
+		if (!result) return null
+		const head = await log.head()
+		if (!head) {
+			throw new NamzuError({
+				code: 'not_found',
+				message: `Session ${sessionId} has an empty log; there is nothing to compact.`,
+				details: { sessionId },
+			})
+		}
+		const { summary, keptMessageIds } = compactionShape(result.messages, ids)
 		await log.append(lease, {
 			type: 'compaction',
 			compactionId: generateMessageId(),

package/src/runtime/query/executor/tool-call-admission.ts

@@ -290,6 +290,9 @@ export async function prepareDirectCall(
 			...(providerInput && !repairUsed && preparation.inputFailure
 				? { inputFailure: preparation.inputFailure }
 				: {}),
+			// The registry's typed reason (e.g. invalid arguments) is what a
+			// host keys its short label on; the message alone is wording.
+			...(preparation.result.facts ? { facts: preparation.result.facts } : {}),
 		}
 	}
 

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

@@ -1201,6 +1201,14 @@ export class IterationOrchestrator {
 						usage: recorder.tokenUsage,
 						budget: recorder.budget?.summary(),
 						cost: recorder.costInfo,
+						...(response.usage.cacheTtlMs !== undefined
+							? {
+									cache: {
+										ttlMs: response.usage.cacheTtlMs,
+										touched: response.usage.cachedTokens + response.usage.cacheWriteTokens > 0,
+									},
+								}
+							: {}),
 						...contextFigures,
 					})
 

package/src/store/budget/disk.ts

@@ -238,6 +238,9 @@ function usageAtLeast(current: TokenUsage | undefined, previous: TokenUsage | un
 	if (current === undefined) return false
 	return Object.entries(previous).every(
 		([field, amount]) =>
-			typeof amount !== 'number' || (current[field as keyof TokenUsage] ?? 0) >= amount,
+			typeof amount !== 'number' ||
+			field === 'cacheTtlMs' ||
+			// `cacheTtlMs` is a per-call lifetime, not a running count: it has no order.
+			((current as unknown as Record<string, number | undefined>)[field] ?? 0) >= amount,
 	)
 }

package/src/tools/admit-facts.ts

@@ -10,6 +10,11 @@ const FAILURE_REASONS: readonly ToolFailureReason[] = [
 	'unknown_tool',
 	'timed_out',
 	'invalid_input',
+	'not_read',
+	'changed_on_disk',
+	'text_not_found',
+	'not_unique',
+	'invalid_arguments',
 ]
 
 const WRITE_OPERATIONS = ['created', 'updated', 'unchanged', 'wrote'] as const
@@ -105,6 +110,7 @@ export function admitToolFacts(value: unknown): ToolFacts | undefined {
 					typeof value.exitCode === 'number' && Number.isSafeInteger(value.exitCode)
 						? value.exitCode
 						: undefined,
+				exitNote: text(value.exitNote),
 				timedOut: flag(value.timedOut),
 				signal: text(value.signal),
 				binary: