@namzu/sdk 27.0.0 → 28.0.0

package/src/bus/breaker.ts

@@ -8,6 +8,7 @@ import type {
 	CircuitBreakerState,
 } from '../types/bus/index.js'
 import type { RunId } from '../types/ids/index.js'
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
 import type { Logger } from '../utils/logger.js'
 
 interface MutableBreakerState {
@@ -34,7 +35,7 @@ export class CircuitBreaker {
 	) {
 		this.failureThreshold = failureThreshold
 		this.resetTimeoutMs = resetTimeoutMs
-		this.log = log.child({ component: 'CircuitBreaker' })
+		this.log = log.child({ [SCOPE_ATTRIBUTE]: 'bus/breaker' })
 		this.emit = emit
 	}
 
@@ -50,8 +51,8 @@ export class CircuitBreaker {
 				if (elapsed >= this.resetTimeoutMs) {
 					breaker.state = 'half_open'
 					this.log.info('circuit breaker transitioning to half_open', {
-						agentRunId,
-						elapsed,
+						'namzu.agent.run_id': agentRunId,
+						'namzu.bus.elapsed': elapsed,
 					})
 					this.emit({ type: 'breaker_half_open', agentRunId })
 					return true
@@ -81,14 +82,16 @@ export class CircuitBreaker {
 			case 'half_open':
 				breaker.state = 'closed'
 				breaker.trippedAt = undefined
-				this.log.info('circuit breaker reset after probe success', { agentRunId })
+				this.log.info('circuit breaker reset after probe success', {
+					'namzu.agent.run_id': agentRunId,
+				})
 				this.emit({ type: 'breaker_probe_success', agentRunId })
 				this.emit({ type: 'breaker_reset', agentRunId })
 				break
 			case 'open':
 				this.log.warn('recordSuccess called while breaker is open', {
-					agentRunId,
-					previousState,
+					'namzu.agent.run_id': agentRunId,
+					'namzu.bus.previous_state': previousState,
 				})
 				break
 			default: {
@@ -118,8 +121,8 @@ export class CircuitBreaker {
 					breaker.state = 'open'
 					breaker.trippedAt = Date.now()
 					this.log.warn('circuit breaker tripped', {
-						agentRunId,
-						consecutiveFailures: breaker.consecutiveFailures,
+						'namzu.agent.run_id': agentRunId,
+						'namzu.bus.consecutive_failures': breaker.consecutiveFailures,
 					})
 					this.emit({
 						type: 'breaker_tripped',
@@ -131,7 +134,9 @@ export class CircuitBreaker {
 			case 'half_open':
 				breaker.state = 'open'
 				breaker.trippedAt = Date.now()
-				this.log.warn('circuit breaker re-tripped from half_open', { agentRunId })
+				this.log.warn('circuit breaker re-tripped from half_open', {
+					'namzu.agent.run_id': agentRunId,
+				})
 				this.emit({ type: 'breaker_probe_failure', agentRunId })
 				this.emit({
 					type: 'breaker_tripped',
@@ -169,7 +174,7 @@ export class CircuitBreaker {
 		breaker.state = 'closed'
 		breaker.consecutiveFailures = 0
 		breaker.trippedAt = undefined
-		this.log.info('circuit breaker manually reset', { agentRunId })
+		this.log.info('circuit breaker manually reset', { 'namzu.agent.run_id': agentRunId })
 		this.emit({ type: 'breaker_reset', agentRunId })
 	}
 

package/src/bus/index.ts

@@ -9,8 +9,10 @@ import { buildProbeContext } from '../probe/context.js'
 import { type ProbeRegistry, probe as defaultProbeRegistry } from '../probe/registry.js'
 import type { AgentBusEvent, AgentBusEventListener } from '../types/bus/index.js'
 import type { RunId } from '../types/ids/index.js'
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
 import type { Logger } from '../utils/logger.js'
 
+import { NAMZU } from '../constants/telemetry/index.js'
 import { CircuitBreaker } from './breaker.js'
 import { FileLockManager } from './lock.js'
 import { EditOwnershipTracker } from './ownership.js'
@@ -49,7 +51,7 @@ export class AgentBus {
 		probeRegistry: ProbeRegistry = defaultProbeRegistry,
 	) {
 		this.config = { ...DEFAULT_AGENT_BUS_CONFIG, ...config }
-		this.log = log.child({ component: 'AgentBus' })
+		this.log = log.child({ [SCOPE_ATTRIBUTE]: 'bus' })
 		this.probes = probeRegistry
 		this.probes.setLogger(log)
 
@@ -85,8 +87,8 @@ export class AgentBus {
 					listener(event)
 				} catch (error) {
 					this.log.error('event listener threw', {
-						eventType: event.type,
-						error: error instanceof Error ? error.message : String(error),
+						'namzu.event.type': event.type,
+						'exception.message': error instanceof Error ? error.message : String(error),
 					})
 				}
 			}
@@ -94,22 +96,22 @@ export class AgentBus {
 	}
 
 	cleanupAgent(runId: RunId): void {
-		this.log.info('cleaning up agent resources', { runId })
+		this.log.info('cleaning up agent resources', { [NAMZU.RUN_ID]: runId })
 		const locksReleased = this.locks.releaseAll(runId)
 		const ownershipsReleased = this.ownership.releaseAll(runId)
 		this.breaker.reset(runId)
 
 		this.log.info('agent cleanup complete', {
-			runId,
-			locksReleased,
-			ownershipsReleased,
+			[NAMZU.RUN_ID]: runId,
+			'namzu.bus.locks_released': locksReleased,
+			'namzu.bus.ownerships_released': ownershipsReleased,
 		})
 	}
 
 	maintenance(): void {
 		const expired = this.locks.expireStale()
 		if (expired > 0) {
-			this.log.info('maintenance: expired stale locks', { count: expired })
+			this.log.info('maintenance: expired stale locks', { 'namzu.bus.count': expired })
 		}
 	}
 }

package/src/bus/lock.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto'
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
 
 import {
 	DEFAULT_LOCK_ACQUIRE_TIMEOUT_MS,
@@ -8,6 +9,7 @@ import {
 } from '../constants/bus/index.js'
 import type { AgentBusEvent, FileLock, LockAcquireResult, LockId } from '../types/bus/index.js'
 import type { RunId } from '../types/ids/index.js'
+import { asLockId } from '../utils/id.js'
 import type { Logger } from '../utils/logger.js'
 
 export interface FileLockManagerConfig {
@@ -35,12 +37,21 @@ export class FileLockManager {
 		config: Partial<FileLockManagerConfig> = {},
 	) {
 		this.config = { ...DEFAULT_CONFIG, ...config }
-		this.log = log.child({ component: 'FileLockManager' })
+		this.log = log.child({ [SCOPE_ATTRIBUTE]: 'bus/lock' })
 		this.emit = emit
 	}
 
 	private generateLockId(): LockId {
-		return `lock_${randomUUID()}`
+		// Through `asLockId` rather than returning the template directly: the
+		// return TYPE alone accepts any `lock_`-shaped string today, and will
+		// stop accepting one the moment the id types go nominal (NZ-SURF-11).
+		//
+		// The UUID stays, and `utils/id.ts` deliberately does not gain a
+		// `generateLockId`. Every generator there mints 12 base-36 characters;
+		// moving this one would change the shape of a value `FileLockManager`
+		// writes to disk, which is a behaviour change wearing a refactor's
+		// clothes. What this task is about is the constructor, not the entropy.
+		return asLockId(`lock_${randomUUID()}`)
 	}
 
 	private getAgentLockSet(owner: RunId): Set<string> {
@@ -59,9 +70,9 @@ export class FileLockManager {
 				return { acquired: true, lock: existing }
 			}
 			this.log.debug('lock denied', {
-				filePath,
-				requester: owner,
-				holder: existing.owner,
+				'namzu.file.path': filePath,
+				'namzu.bus.requester': owner,
+				'namzu.bus.holder': existing.owner,
 			})
 			this.emit({
 				type: 'lock_denied',
@@ -75,9 +86,9 @@ export class FileLockManager {
 		const agentLockSet = this.getAgentLockSet(owner)
 		if (agentLockSet.size >= this.config.maxLocksPerAgent) {
 			this.log.warn('max locks per agent reached', {
-				owner,
-				currentCount: agentLockSet.size,
-				max: this.config.maxLocksPerAgent,
+				'namzu.bus.owner': owner,
+				'namzu.bus.current_count': agentLockSet.size,
+				'namzu.bus.max': this.config.maxLocksPerAgent,
 			})
 			return { acquired: false, holder: owner, filePath }
 		}
@@ -95,7 +106,11 @@ export class FileLockManager {
 		this.locks.set(filePath, lock)
 		agentLockSet.add(filePath)
 
-		this.log.debug('lock acquired', { lockId, filePath, owner })
+		this.log.debug('lock acquired', {
+			'namzu.lock.id': lockId,
+			'namzu.file.path': filePath,
+			'namzu.bus.owner': owner,
+		})
 		this.emit({ type: 'lock_acquired', lockId, filePath, owner })
 		return { acquired: true, lock }
 	}
@@ -118,7 +133,9 @@ export class FileLockManager {
 		const holder = this.locks.get(filePath)
 		return {
 			acquired: false,
-			holder: holder?.owner ?? ('' as RunId),
+			// Omitted rather than faked when the lock has no recorded holder —
+			// see `LockAcquireResult` for why the field is optional.
+			...(holder ? { holder: holder.owner } : {}),
 			filePath,
 		}
 	}
@@ -137,9 +154,9 @@ export class FileLockManager {
 		}
 
 		this.log.debug('lock released', {
-			lockId: existing.lockId,
-			filePath,
-			owner,
+			'namzu.lock.id': existing.lockId,
+			'namzu.file.path': filePath,
+			'namzu.bus.owner': owner,
 		})
 		this.emit({
 			type: 'lock_released',
@@ -160,9 +177,9 @@ export class FileLockManager {
 			if (lock && lock.owner === owner) {
 				this.locks.delete(filePath)
 				this.log.debug('lock released (cleanup)', {
-					lockId: lock.lockId,
-					filePath,
-					owner,
+					'namzu.lock.id': lock.lockId,
+					'namzu.file.path': filePath,
+					'namzu.bus.owner': owner,
 				})
 				this.emit({
 					type: 'lock_released',
@@ -219,9 +236,9 @@ export class FileLockManager {
 		}
 
 		this.log.info('lock expired', {
-			lockId: lock.lockId,
-			filePath,
-			owner: lock.owner,
+			'namzu.lock.id': lock.lockId,
+			'namzu.file.path': filePath,
+			'namzu.bus.owner': lock.owner,
 		})
 		this.emit({
 			type: 'lock_expired',

package/src/bus/ownership.ts

@@ -1,4 +1,5 @@
 import path from 'node:path'
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
 
 import type { AgentBusEvent, FileOwnership, OwnershipClaimResult } from '../types/bus/index.js'
 import type { RunId } from '../types/ids/index.js'
@@ -10,7 +11,7 @@ export class EditOwnershipTracker {
 	private readonly emit: (event: AgentBusEvent) => void
 
 	constructor(log: Logger, emit: (event: AgentBusEvent) => void) {
-		this.log = log.child({ component: 'EditOwnershipTracker' })
+		this.log = log.child({ [SCOPE_ATTRIBUTE]: 'bus/ownership' })
 		this.emit = emit
 	}
 
@@ -24,9 +25,9 @@ export class EditOwnershipTracker {
 
 		if (existing && existing.owner !== owner) {
 			this.log.debug('ownership claim denied', {
-				filePath: normalized,
-				requester: owner,
-				currentOwner: existing.owner,
+				'namzu.file.path': normalized,
+				'namzu.bus.requester': owner,
+				'namzu.bus.current_owner': existing.owner,
 			})
 			this.emit({
 				type: 'ownership_denied',
@@ -48,7 +49,7 @@ export class EditOwnershipTracker {
 		}
 		this.ownerships.set(normalized, ownership)
 
-		this.log.debug('ownership claimed', { filePath: normalized, owner })
+		this.log.debug('ownership claimed', { 'namzu.file.path': normalized, 'namzu.bus.owner': owner })
 		this.emit({ type: 'ownership_claimed', filePath: normalized, owner })
 		return { claimed: true, ownership }
 	}
@@ -62,7 +63,10 @@ export class EditOwnershipTracker {
 		}
 
 		this.ownerships.delete(normalized)
-		this.log.debug('ownership released', { filePath: normalized, previousOwner: owner })
+		this.log.debug('ownership released', {
+			'namzu.file.path': normalized,
+			'namzu.bus.previous_owner': owner,
+		})
 		this.emit({ type: 'ownership_released', filePath: normalized, previousOwner: owner })
 		return true
 	}
@@ -82,7 +86,11 @@ export class EditOwnershipTracker {
 		}
 		this.ownerships.set(normalized, transferred)
 
-		this.log.info('ownership transferred', { filePath: normalized, from, to })
+		this.log.info('ownership transferred', {
+			'namzu.file.path': normalized,
+			'namzu.bus.from': from,
+			'namzu.bus.to': to,
+		})
 		this.emit({ type: 'ownership_transferred', filePath: normalized, from, to })
 		return true
 	}
@@ -93,8 +101,8 @@ export class EditOwnershipTracker {
 			if (ownership.owner === owner) {
 				this.ownerships.delete(normalized)
 				this.log.debug('ownership released (cleanup)', {
-					filePath: normalized,
-					previousOwner: owner,
+					'namzu.file.path': normalized,
+					'namzu.bus.previous_owner': owner,
 				})
 				this.emit({
 					type: 'ownership_released',

package/src/compaction/context-window.ts

@@ -107,7 +107,15 @@ export function lookupContextWindow(model: string | undefined): number | undefin
 
 export interface ResolvedContextWindow {
 	readonly tokens: number
-	readonly source: 'config' | 'model-table' | 'default'
+	/**
+	 * Where the number came from, ranked in that order.
+	 *
+	 * `'provider'` sits between the two for a reason: a host that set a
+	 * number said what they want and outranks any discovery, while the
+	 * table is a guess maintained by hand and the vendor's own answer is
+	 * not.
+	 */
+	readonly source: 'config' | 'provider' | 'model-table' | 'default'
 }
 
 /**
@@ -120,10 +128,24 @@ export interface ResolvedContextWindow {
 export function resolveContextWindow(
 	configured: number | undefined,
 	model: string | undefined,
+	/**
+	 * What the driver said, already resolved.
+	 *
+	 * A plain number rather than a promise, because both call sites are
+	 * synchronous and sit in the hot loop. Resolving happens once at the
+	 * start of a run; this parameter is that answer being carried in.
+	 */
+	providerReported?: number,
 ): ResolvedContextWindow {
 	if (configured !== undefined && configured > 0) {
 		return { tokens: configured, source: 'config' }
 	}
+	if (providerReported !== undefined && providerReported > 0) {
+		return { tokens: providerReported, source: 'provider' }
+	}
+	// A driver that resolved `undefined` falls through to HERE, not to the
+	// default. "I asked and it does not know" leaves the table exactly as
+	// authoritative as it was before anyone asked.
 	const known = lookupContextWindow(model)
 	if (known !== undefined) {
 		return { tokens: known, source: 'model-table' }

package/src/compaction/index.ts

@@ -57,3 +57,9 @@ export {
 	DEFAULT_MIN_CHARS_TO_CLEAR,
 } from './tool-result-editing.js'
 export type { ToolResultEditConfig, ToolResultEditOutcome } from './tool-result-editing.js'
+
+// Host-callable compaction: "compact this conversation" as an action a host
+// can offer, rather than something that only happens when a threshold trips.
+export { compactNow, compactRegion } from './manual.js'
+export type { CompactionResult, CompactNowInput, CompactRegionInput } from './manual.js'
+export { COMPACTION_HEADER, buildCompactionMessage, isCompactionMessage } from './summary.js'

package/src/compaction/manual.ts

@@ -0,0 +1,177 @@
+import type { CompactionConfig } from '../config/runtime.js'
+import { NamzuError } from '../types/errors/index.js'
+import type { Message } from '../types/message/index.js'
+import type { LLMProvider } from '../types/provider/index.js'
+import { resolveContextWindow } from './context-window.js'
+import { findDanglingMessages, findSafeTrimIndex } from './dangling.js'
+import { WorkingStateManager } from './manager.js'
+import { planCompaction } from './plan.js'
+import { buildCompactionMessage, isCompactionMessage } from './summary.js'
+import { buildVerifiedSummary } from './verifier.js'
+
+/**
+ * Compaction a host can ask for, rather than one that only happens to it.
+ *
+ * `runCompactionCheck` was the only entry point in the kernel and it was
+ * exported from nowhere. So a host could not offer "compact this
+ * conversation", could not shrink an idle session sitting between turns,
+ * and could not collapse a span it had chosen — every compaction had to
+ * wait for the in-loop threshold or a provider overflow retry.
+ *
+ * These are that entry point, built on the planner rather than on a second
+ * copy of the boundary arithmetic. Nothing here touches an
+ * `IterationContext`: there is no run, which is the whole point.
+ */
+
+export interface CompactionResult {
+	/** The new history. A fresh array — the input is never edited. */
+	readonly messages: readonly Message[]
+	/** How many messages the pass removed. Always at least one. */
+	readonly shed: number
+	/** The summary that replaced them, as it appears in `messages`. */
+	readonly summary: Message
+}
+
+export interface CompactNowInput {
+	readonly messages: readonly Message[]
+	readonly config: CompactionConfig
+	readonly provider: LLMProvider
+	readonly model?: string
+	readonly contextWindowTokens?: number
+}
+
+/** Assembles the new history from a plan's partition plus its summary. */
+function splice(
+	systemMessages: readonly Message[],
+	summaryBody: string,
+	recentMessages: readonly Message[],
+): { messages: Message[]; summary: Message } {
+	const summary = buildCompactionMessage(summaryBody)
+	// Any PRIOR summary is dropped: the state a summary is built from is
+	// cumulative, so a new one supersedes it. Without this the never-trimmed
+	// floor accumulates one redundant block per pass, unbounded.
+	const preserved = systemMessages.filter(
+		(m) => !isCompactionMessage(typeof m.content === 'string' ? m.content : null),
+	)
+	return { messages: [...preserved, summary, ...recentMessages], summary }
+}
+
+/**
+ * Compact a history now, whatever its size.
+ *
+ * Returns `null` when there is nothing to shed — not a zero-shed result.
+ * A caller has to be able to tell "I compacted and it did nothing" from "I
+ * compacted", and an outcome object reporting zero is the shape that gets
+ * logged as a successful pass and shown to a user as work done.
+ */
+export async function compactNow(input: CompactNowInput): Promise<CompactionResult | null> {
+	const window = resolveContextWindow(
+		input.contextWindowTokens ?? input.config.contextWindowTokens,
+		input.model,
+	)
+
+	// `force` because a host asked. The threshold exists to decide whether an
+	// automatic pass is worth its model call; somebody clicking "compact"
+	// has already answered that question.
+	const plan = planCompaction({
+		messages: input.messages,
+		config: input.config,
+		contextWindowTokens: window.tokens,
+		estimatedTokens: window.tokens,
+		force: true,
+		skipToolResultClear: true,
+	})
+	if (plan.kind !== 'plan') return null
+
+	const manager = new WorkingStateManager(input.config)
+	const body = await buildVerifiedSummary(
+		manager,
+		[...plan.olderMessages],
+		input.provider,
+		input.config,
+		undefined,
+		input.model ?? '',
+	)
+
+	const { messages, summary } = splice(plan.systemMessages, body, plan.recentMessages)
+	return { messages, shed: input.messages.length - messages.length, summary }
+}
+
+export interface CompactRegionInput extends CompactNowInput {
+	/** First index to summarise, inclusive. */
+	readonly start: number
+	/** One past the last index to summarise. */
+	readonly end: number
+}
+
+/**
+ * Compact exactly the span a host chose, or refuse.
+ *
+ * REFUSES rather than repairing. Snapping a bad edge to the nearest safe
+ * one would return a different span than the one asked for, and the caller
+ * — who picked those indices from something they were looking at — has no
+ * way to notice: the result is a valid history that summarised the wrong
+ * messages. `refuse-do-not-degrade`, and the offending index is named so
+ * the caller can move it themselves.
+ */
+export async function compactRegion(input: CompactRegionInput): Promise<CompactionResult | null> {
+	const { messages, start, end } = input
+
+	if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end > messages.length) {
+		throw new NamzuError({
+			code: 'invalid_config',
+			message: `compactRegion: [${start}, ${end}) is not a range inside a history of ${messages.length} messages.`,
+			details: { start, end, length: messages.length },
+			retryable: false,
+		})
+	}
+	if (end - start < 1) return null
+
+	for (const [label, index] of [
+		['start', start],
+		['end', end],
+	] as const) {
+		// `findSafeTrimIndex` returns the nearest index that does NOT split a
+		// tool-call pair. Anything other than the index itself means this edge
+		// sits between an assistant's `tool_use` and its `tool_result`, and
+		// cutting there leaves the provider a result with no matching call —
+		// which it rejects on the next turn.
+		if (findSafeTrimIndex(messages as Message[], index) !== index) {
+			throw new NamzuError({
+				code: 'invalid_config',
+				message: `compactRegion: ${label} index ${index} splits a tool_use/tool_result pair. Move it to a boundary between turns.`,
+				details: { [label]: index, start, end },
+				retryable: false,
+			})
+		}
+	}
+
+	const manager = new WorkingStateManager(input.config)
+	const body = await buildVerifiedSummary(
+		manager,
+		messages.slice(start, end),
+		input.provider,
+		input.config,
+		undefined,
+		input.model ?? '',
+	)
+
+	const summary = buildCompactionMessage(body)
+	const out = [...messages.slice(0, start), summary, ...messages.slice(end)]
+
+	// Checked after the splice, not only before it. The edges being
+	// individually safe does not make the RESULT valid — a span whose
+	// interior held one half of a pair straddling `start` would pass both
+	// edge checks and produce an orphan.
+	const dangling = findDanglingMessages(out)
+	if (!dangling.isValid) {
+		throw new NamzuError({
+			code: 'invalid_config',
+			message: `compactRegion: summarising [${start}, ${end}) would leave an unmatched tool result. Widen the span to cover the whole exchange.`,
+			details: { start, end },
+			retryable: false,
+		})
+	}
+
+	return { messages: out, shed: messages.length - out.length, summary }
+}