@namzu/sdk 62.8.0 → 62.9.0

package/src/compaction/plan.ts

@@ -4,7 +4,12 @@ import { resolveTriggerThreshold } from './context-window.js'
 import { findSafeTrimIndex } from './dangling.js'
 import { buildGoal } from './salience/goal.js'
 import { scoreMessages } from './salience/score.js'
-import { type WorkingSetPlan, planWorkingSet } from './salience/working-set.js'
+import {
+	type WorkingSetPlan,
+	hasEvictableMessage,
+	planNothingToShed,
+	planWorkingSet,
+} from './salience/working-set.js'
 import { estimateMessageTokens, estimateMessagesTokens } from './token-estimate.js'
 import { clearStaleToolResults } from './tool-result-editing.js'
 
@@ -136,6 +141,33 @@ export function naiveKeepStartByTokens(messages: readonly Message[], budgetToken
 /** Where the salience pass holds the context, as a fraction of the window. */
 export const DEFAULT_SOFT_TARGET = 0.5
 
+/**
+ * The context size, in tokens, a salience pass sheds down to: the soft
+ * target less the configured headroom. With no headroom (the default) this
+ * is the soft target, computed exactly as it always was.
+ */
+export function salienceTargetTokens(config: CompactionConfig, windowTokens: number): number {
+	const soft = config.softTarget ?? DEFAULT_SOFT_TARGET
+	const headroom = config.softTargetHeadroom ?? 0
+	return Math.floor(windowTokens * (headroom > 0 ? Math.max(0, soft - headroom) : soft))
+}
+
+/**
+ * Whether a salience pass could shed anything from `messages` at all: false
+ * is exact (the pass would make no action whatever the scores are), true is
+ * "go and score". See {@link hasEvictableMessage}.
+ */
+export function canShedSalienceWorkingSet(
+	messages: readonly Message[],
+	config: CompactionConfig,
+): boolean {
+	return hasEvictableMessage(messages, {
+		minToolResultChars: config.minToolResultCharsToClear,
+		...(config.preserveToolResultsFrom ? { preserveTools: config.preserveToolResultsFrom } : {}),
+		keepRecentMessages: config.keepRecentMessages,
+	})
+}
+
 export function planSalienceWorkingSet(input: {
 	readonly messages: readonly Message[]
 	readonly config: CompactionConfig
@@ -146,19 +178,29 @@ export function planSalienceWorkingSet(input: {
 	readonly openTasks?: readonly string[]
 }): Extract<CompactionPlan, { kind: 'cleared' }> & { readonly working: WorkingSetPlan } {
 	const { config, estimatedTokens, contextWindowTokens: budget } = input
-	const goal = buildGoal(input.messages, {
-		...(input.openTasks ? { openTasks: input.openTasks } : {}),
-	})
-	const scored = scoreMessages(input.messages, {
-		goal,
-		keepRecentMessages: config.keepRecentMessages,
-	})
-	const working = planWorkingSet(input.messages, scored, {
+	const workingOptions = {
 		estimatedTokens,
-		targetTokens: Math.floor(budget * (config.softTarget ?? DEFAULT_SOFT_TARGET)),
+		targetTokens: salienceTargetTokens(config, budget),
 		minToolResultChars: config.minToolResultCharsToClear,
 		...(config.preserveToolResultsFrom ? { preserveTools: config.preserveToolResultsFrom } : {}),
-	})
+	}
+	// Nothing the pass may shed, whatever the scores say: every tool result
+	// is small, cleared, an error or from a preserved tool, and every
+	// narration is short or already cut. Scoring every message to learn that
+	// is the whole cost of a pass that can do nothing, and it ran on every
+	// turn from the soft target until the summary trigger.
+	const working = canShedSalienceWorkingSet(input.messages, config)
+		? planWorkingSet(
+				input.messages,
+				scoreMessages(input.messages, {
+					goal: buildGoal(input.messages, {
+						...(input.openTasks ? { openTasks: input.openTasks } : {}),
+					}),
+					keepRecentMessages: config.keepRecentMessages,
+				}),
+				workingOptions,
+			)
+		: planNothingToShed(input.messages, workingOptions)
 	return {
 		kind: 'cleared',
 		messages: working.messages,

package/src/compaction/salience/minhash.ts

@@ -48,6 +48,26 @@ export function similarity(a: Uint32Array, b: Uint32Array): number {
 	return same / HASHES
 }
 
+/**
+ * {@link similarity}, or 0 when it is below `floor`.
+ *
+ * The scorer reads a similarity below one half as no similarity at all, so
+ * a comparison that has already missed enough slots to land under the floor
+ * can stop there. For a pair that reaches the floor the answer is the same
+ * number `similarity` returns, slot for slot.
+ */
+export function similarityAtLeast(a: Uint32Array, b: Uint32Array, floor: number): number {
+	const allowedMisses = HASHES - Math.ceil(floor * HASHES)
+	let misses = 0
+	for (let slot = 0; slot < HASHES; slot += 1) {
+		if (a[slot] !== b[slot]) {
+			misses += 1
+			if (misses > allowedMisses) return 0
+		}
+	}
+	return (HASHES - misses) / HASHES
+}
+
 export function isEmptySignature(signature: Uint32Array): boolean {
 	return signature.every((h) => h === 0xffffffff)
 }

package/src/compaction/salience/score.ts

@@ -26,7 +26,7 @@ import type { AssistantMessage, Message, ToolMessage } from '../../types/message
 import { findRetainedIndices } from '../retention.js'
 import { estimateMessageTokens } from '../token-estimate.js'
 import { type Bm25Document, bm25Score, buildIndex, indexDocument } from './bm25.js'
-import { isEmptySignature, minhash, similarity } from './minhash.js'
+import { isEmptySignature, minhash, similarityAtLeast } from './minhash.js'
 import { tokenize } from './tokenize.js'
 
 export interface SalienceWeights {
@@ -119,6 +119,54 @@ function citable(tokens: readonly string[]): Set<string> {
 	return out
 }
 
+/**
+ * What the scorer derives from one message's text, and nothing that depends
+ * on the rest of the history: the term frequencies BM25 reads, the
+ * identifiers a later turn could cite, the MinHash signature and a key for
+ * "byte-identical signature".
+ *
+ * A pass scored every message from its raw text every time, and the text of
+ * a message that is already in the history does not change between passes.
+ * The cost of a pass was therefore proportional to every byte in the
+ * history, paid again on each pass, and the largest part of it was hashing
+ * shingles. Held per message OBJECT, a pass pays for the messages it has not
+ * seen and for the arithmetic that does depend on the whole history (the
+ * corpus statistics, recency, the redundancy comparison).
+ *
+ * Keyed by object identity and validated by the text it was computed from: a
+ * message that is replaced (a stub is a copy) is a different object, and one
+ * that is edited in place fails the text comparison, so a stale entry is
+ * never read. Weakly held: an entry goes with its message.
+ */
+interface MessageFeatures {
+	readonly text: string
+	readonly tokenCount: number
+	readonly document: Bm25Document
+	readonly citable: ReadonlySet<string>
+	readonly signature: Uint32Array
+	/** Equal keys mean equal signatures, so a similarity of exactly 1. */
+	readonly signatureKey: string
+}
+
+const FEATURES = new WeakMap<Message, MessageFeatures>()
+
+function featuresOf(message: Message, text: string): MessageFeatures {
+	const cached = FEATURES.get(message)
+	if (cached !== undefined && cached.text === text) return cached
+	const tokens = tokenize(text)
+	const signature = minhash(tokens)
+	const features: MessageFeatures = {
+		text,
+		tokenCount: tokens.length,
+		document: indexDocument(text, tokens),
+		citable: citable(tokens),
+		signature,
+		signatureKey: String.fromCharCode(...new Uint16Array(signature.buffer)),
+	}
+	FEATURES.set(message, features)
+	return features
+}
+
 export function scoreMessages(
 	messages: readonly Message[],
 	options: ScoreOptions,
@@ -129,12 +177,9 @@ export function scoreMessages(
 		weights: { ...DEFAULT_SALIENCE_WEIGHTS, ...options.config?.weights },
 	}
 	const n = messages.length
-	const texts = messages.map(messageText)
+	const features = messages.map((message) => featuresOf(message, messageText(message)))
 	const richContent = messages.map(hasRichContent)
-	const tokenLists = texts.map(tokenize)
-	const documents: Bm25Document[] = texts.map((text, i) =>
-		indexDocument(text, tokenLists[i] as string[]),
-	)
+	const documents: Bm25Document[] = features.map((f) => f.document)
 	const index = buildIndex(documents)
 	const goalTokens = tokenize(options.goal)
 
@@ -156,33 +201,64 @@ export function scoreMessages(
 	)
 
 	// Citation index: everything a LATER assistant turn or tool input names.
-	// Built once, suffix-wise, so each message asks "does anything after me
-	// cite my identifiers" in one lookup.
-	const citedAfter: Set<string>[] = new Array(n)
-	let running = new Set<string>()
-	for (let i = n - 1; i >= 0; i -= 1) {
-		citedAfter[i] = running
+	// For each identifier, the last message that names it: a message asks
+	// "does anything after me cite my identifiers" as "is the last citation
+	// of this identifier after me". The same answer as a set of everything
+	// after each message, without building n sets of up to n identifiers.
+	const lastCited = new Map<string, number>()
+	for (let i = 0; i < n; i += 1) {
 		const message = messages[i] as Message
-		if (message.role === 'assistant' || message.role === 'user') {
-			running = new Set([...running, ...citable(tokenLists[i] as string[])])
-		}
+		if (message.role !== 'assistant' && message.role !== 'user') continue
+		for (const token of (features[i] as MessageFeatures).citable) lastCited.set(token, i)
 	}
 
-	// Redundancy: the highest similarity to any later message of the same
-	// role, and a full demotion when a later assistant turn repeats this
-	// message's tool call exactly.
-	const signatures = tokenLists.map(minhash)
+	// A full demotion when a later assistant turn repeats this message's
+	// tool call exactly: for each call, the last message that makes it.
 	const callKeys = messages.map((m) =>
 		isAssistantWithCalls(m)
 			? (m.toolCalls ?? []).map((c) => `${c.function.name}:${c.function.arguments}`)
 			: [],
 	)
-	const laterCallKeys: Set<string>[] = new Array(n)
-	let calls = new Set<string>()
+	const lastCalled = new Map<string, number>()
+	for (let i = 0; i < n; i += 1) {
+		for (const key of callKeys[i] as string[]) lastCalled.set(key, i)
+	}
+
+	// Redundancy: the highest similarity to any later message of the same
+	// role. Walked from the end so the later messages of each role are the
+	// ones already seen; a signature identical to one of them is a
+	// similarity of exactly 1, the most there is, and ends the scan.
+	// Below the lower of one half and the duplicate threshold a similarity
+	// is read as none (see the redundancy step of the score), so the
+	// comparison need not finish it.
+	const floor = Math.min(0.5, config.duplicateThreshold)
+	const redundancyOf: number[] = new Array(n).fill(0)
+	const laterSignatures = new Map<Message['role'], Uint32Array[]>()
+	const laterKeys = new Map<Message['role'], Set<string>>()
 	for (let i = n - 1; i >= 0; i -= 1) {
-		laterCallKeys[i] = calls
-		if ((callKeys[i] as string[]).length > 0)
-			calls = new Set([...calls, ...(callKeys[i] as string[])])
+		const message = messages[i] as Message
+		// A caption or a repeated call cannot prove that two screenshots or
+		// documents contain the same evidence. The lexical scorer has no
+		// access to their meaning, so it must not call those messages duplicates.
+		if (richContent[i]) continue
+		const own = features[i] as MessageFeatures
+		const sameRole = laterSignatures.get(message.role) ?? []
+		const sameRoleKeys = laterKeys.get(message.role) ?? new Set<string>()
+		let redundancy = 0
+		if (!isEmptySignature(own.signature)) {
+			if (sameRoleKeys.has(own.signatureKey)) redundancy = 1
+			else {
+				for (const other of sameRole) {
+					const sim = similarityAtLeast(own.signature, other, floor)
+					if (sim > redundancy) redundancy = sim
+				}
+			}
+		}
+		redundancyOf[i] = redundancy
+		sameRole.push(own.signature)
+		sameRoleKeys.add(own.signatureKey)
+		laterSignatures.set(message.role, sameRole)
+		laterKeys.set(message.role, sameRoleKeys)
 	}
 
 	// Protection.
@@ -239,8 +315,8 @@ export function scoreMessages(
 			// An instruction is used by everything after it; an acknowledgment
 			// ("ok, go on") is not an instruction. The difference is whether it
 			// names anything or says more than a few words.
-			const tokens = tokenLists[i] as string[]
-			utility = citable(tokens).size > 0 || tokens.length >= 6 ? 1 : 0.2
+			const own = features[i] as MessageFeatures
+			utility = own.citable.size > 0 || own.tokenCount >= 6 ? 1 : 0.2
 		} else if (message.role === 'tool') {
 			// Used is used: one identifier from this result named by a later
 			// turn is the evidence, and a count would let the recency of
@@ -248,24 +324,17 @@ export function scoreMessages(
 			// for. The eval that placed the account id deep in an early dump
 			// and cited it later watched the salience pass clear it under a
 			// thirds rule.
-			const mine = citable(tokenLists[i] as string[])
-			let hits = 0
-			for (const token of mine) if ((citedAfter[i] as Set<string>).has(token)) hits += 1
-			utility = hits > 0 ? 1 : 0
+			let cited = false
+			for (const token of (features[i] as MessageFeatures).citable) {
+				if ((lastCited.get(token) ?? -1) > i) {
+					cited = true
+					break
+				}
+			}
+			utility = cited ? 1 : 0
 		} else if (isAssistantWithCalls(message)) utility = 0.5
 
-		let redundancy = 0
-		const signature = signatures[i] as Uint32Array
-		// A caption or a repeated call cannot prove that two screenshots or
-		// documents contain the same evidence. The lexical scorer has no
-		// access to their meaning, so it must not call those messages duplicates.
-		if (!richContent[i] && !isEmptySignature(signature)) {
-			for (let j = i + 1; j < n; j += 1) {
-				if (richContent[j] || (messages[j] as Message).role !== message.role) continue
-				const sim = similarity(signature, signatures[j] as Uint32Array)
-				if (sim > redundancy) redundancy = sim
-			}
-		}
+		let redundancy = redundancyOf[i] as number
 		if (redundancy < config.duplicateThreshold) redundancy = redundancy >= 0.5 ? redundancy : 0
 		else redundancy = 1
 		if (message.role === 'tool' && !richContent[i]) {
@@ -279,7 +348,7 @@ export function scoreMessages(
 				)
 				if (call) {
 					const key = `${call.function.name}:${call.function.arguments}`
-					if ((laterCallKeys[i] as Set<string>).has(key)) redundancy = 1
+					if ((lastCalled.get(key) ?? -1) > i) redundancy = 1
 					break
 				}
 			}

package/src/compaction/salience/working-set.ts

@@ -73,14 +73,18 @@ export function isStubbedNarration(content: unknown): boolean {
 	return typeof content === 'string' && content.includes(STUB_MARK)
 }
 
-export function planWorkingSet(
+/** What decides whether a message is something the pass may shed at all. */
+interface EvictionRules {
+	readonly minTool: number
+	readonly minNarration: number
+	readonly preserve: ReadonlySet<string>
+	readonly toolNameByCallId: ReadonlyMap<string, string>
+}
+
+function evictionRules(
 	messages: readonly Message[],
-	scored: readonly ScoredMessage[],
-	options: WorkingSetOptions,
-): WorkingSetPlan {
-	const minTool = options.minToolResultChars ?? 1_000
-	const minNarration = options.minNarrationChars ?? 240
-	const preserve = new Set(options.preserveTools ?? [])
+	options: Pick<WorkingSetOptions, 'minToolResultChars' | 'minNarrationChars' | 'preserveTools'>,
+): EvictionRules {
 	const toolNameByCallId = new Map<string, string>()
 	for (const m of messages) {
 		if (m.role !== 'assistant') continue
@@ -88,6 +92,87 @@ export function planWorkingSet(
 			toolNameByCallId.set(call.id, call.function.name)
 		}
 	}
+	return {
+		minTool: options.minToolResultChars ?? 1_000,
+		minNarration: options.minNarrationChars ?? 240,
+		preserve: new Set(options.preserveTools ?? []),
+		toolNameByCallId,
+	}
+}
+
+/**
+ * Whether the pass could clear or stub this message, ignoring only what
+ * protection decides (the floor, the recent turns, retained turns, a pair
+ * with a protected half) and what the score decides. The one place the
+ * eligibility rules live: {@link planWorkingSet} asks it of each unprotected
+ * message, and {@link hasEvictableMessage} asks it of every message.
+ */
+function evictionKind(m: Message, tokens: number, rules: EvictionRules): 'clear' | 'stub' | null {
+	if (tokens === 0) return null
+	if (m.role === 'tool') {
+		const tool = m as ToolMessage
+		if (tool.isError || isClearedToolResult(tool.content)) return null
+		if (rules.preserve.has(rules.toolNameByCallId.get(tool.toolCallId) ?? '')) return null
+		if (tokens * CHARS_PER_TOKEN < rules.minTool) return null
+		return 'clear'
+	}
+	if (m.role === 'assistant' && !Array.isArray((m as AssistantMessage).toolCalls)) {
+		const text = typeof m.content === 'string' ? m.content : ''
+		if (text.length < rules.minNarration || isStubbedNarration(text)) return null
+		return 'stub'
+	}
+	return null
+}
+
+/**
+ * A cheap count of whether anything at all is left for the pass to shed:
+ * false means {@link planWorkingSet} would return no action whatever the
+ * scores are, so scoring can be skipped. It leaves out the two protections
+ * that are only a position (the leading system run and the last
+ * `keepRecentMessages`); retained turns, tool-call pairs and the goal floor
+ * are not looked at. True is therefore only "go and look", and a false is
+ * exact.
+ */
+export function hasEvictableMessage(
+	messages: readonly Message[],
+	options: Pick<WorkingSetOptions, 'minToolResultChars' | 'minNarrationChars' | 'preserveTools'> & {
+		readonly keepRecentMessages: number
+	},
+): boolean {
+	const rules = evictionRules(messages, options)
+	let floorEnd = 0
+	while (floorEnd < messages.length && messages[floorEnd]?.role === 'system') floorEnd += 1
+	const end = Math.max(floorEnd, messages.length - options.keepRecentMessages)
+	for (let i = floorEnd; i < end; i += 1) {
+		const m = messages[i] as Message
+		if (evictionKind(m, estimateMessageTokens(m), rules) !== null) return true
+	}
+	return false
+}
+
+/** The plan of a pass that sheds nothing: every message as it was. */
+export function planNothingToShed(
+	messages: readonly Message[],
+	options: Pick<WorkingSetOptions, 'estimatedTokens' | 'targetTokens'>,
+): WorkingSetPlan {
+	return {
+		messages: [...messages],
+		actions: [],
+		clearedCount: 0,
+		stubbedCount: 0,
+		charsReclaimed: 0,
+		reclaimedTokens: 0,
+		reachedTarget: options.estimatedTokens - options.targetTokens <= 0,
+	}
+}
+
+export function planWorkingSet(
+	messages: readonly Message[],
+	scored: readonly ScoredMessage[],
+	options: WorkingSetOptions,
+): WorkingSetPlan {
+	const rules = evictionRules(messages, options)
+	const { toolNameByCallId } = rules
 
 	// Ordered by salience, not salience per token. Per token was the plan's
 	// first answer and it evicts the wrong thing: a large result the goal
@@ -104,31 +189,17 @@ export function planWorkingSet(
 	}
 	const candidates: Candidate[] = []
 	for (const s of scored) {
-		if (s.protected !== null || s.tokens === 0) continue
+		if (s.protected !== null) continue
 		const m = messages[s.index] as Message
-		if (m.role === 'tool') {
-			const tool = m as ToolMessage
-			if (tool.isError || isClearedToolResult(tool.content)) continue
-			if (preserve.has(toolNameByCallId.get(tool.toolCallId) ?? '')) continue
-			if (s.tokens * CHARS_PER_TOKEN < minTool) continue
-			candidates.push({
-				index: s.index,
-				kind: 'clear',
-				salience: s.salience,
-				tokens: s.tokens,
-				goalBound: s.relevance >= 0.5 || s.utility >= 1,
-			})
-		} else if (m.role === 'assistant' && !Array.isArray((m as AssistantMessage).toolCalls)) {
-			const text = typeof m.content === 'string' ? m.content : ''
-			if (text.length < minNarration || isStubbedNarration(text)) continue
-			candidates.push({
-				index: s.index,
-				kind: 'stub',
-				salience: s.salience,
-				tokens: s.tokens,
-				goalBound: s.relevance >= 0.5 || s.utility >= 1,
-			})
-		}
+		const kind = evictionKind(m, s.tokens, rules)
+		if (kind === null) continue
+		candidates.push({
+			index: s.index,
+			kind,
+			salience: s.salience,
+			tokens: s.tokens,
+			goalBound: s.relevance >= 0.5 || s.utility >= 1,
+		})
 	}
 	candidates.sort((a, b) => a.salience - b.salience || b.tokens - a.tokens || a.index - b.index)
 	const maxSalience = candidates.reduce((m, c) => Math.max(m, c.salience), Number.NEGATIVE_INFINITY)

package/src/config/runtime.ts

@@ -32,6 +32,20 @@ export const CompactionConfigSchema = z.object({
 	 * `triggerThreshold` summarises. The context is held around here.
 	 */
 	softTarget: z.number().min(0).max(1).optional(),
+	/**
+	 * `salience` only: how far below `softTarget`, as a fraction of the
+	 * window, a pass sheds. A pass still starts when the context reaches the
+	 * soft target, but it then keeps shedding until the context is
+	 * `softTargetHeadroom` of the window under it, so the next pass is needed
+	 * only after that headroom has been used instead of on the next turn.
+	 * Fewer passes, and the request is rewritten (a prompt cache's prefix
+	 * broken) once per headroom instead of once per turn; the cost is that
+	 * the context is held that much lower, so that much less history stays
+	 * whole. The messages shed are the same ones in the same order, only
+	 * earlier. Absent or `0`, the default, a pass sheds to the soft target
+	 * and no further, exactly as before.
+	 */
+	softTargetHeadroom: z.number().min(0).max(1).optional(),
 	/**
 	 * Optional model context-window size (tokens) the compaction trigger
 	 * measures the CURRENT window against. NO default: when omitted the