@namzu/sdk 0.1.4 → 0.1.5-rc.1-fix

package/src/compaction/dangling.ts

@@ -0,0 +1,321 @@
+import type { Message } from '../types/message/index.js'
+
+/**
+ * Represents the result of scanning messages for dangling tool call/result pairs.
+ * Used to identify which messages should be removed to ensure message validity.
+ */
+export interface DanglingResult {
+	/** Indices of assistant messages with unmatched tool calls */
+	assistantsWithUnmatchedCalls: number[]
+	/** Indices of tool messages with no matching assistant tool call */
+	orphanedToolMessages: number[]
+	/** Whether the message sequence is valid (no dangling messages) */
+	isValid: boolean
+}
+
+/**
+ * Named constants for dangling message detection logic.
+ */
+const CONSTANTS = {
+	/** Role sentinel for tool message identification */
+	TOOL_ROLE: 'tool',
+	/** Role sentinel for assistant message identification */
+	ASSISTANT_ROLE: 'assistant',
+} as const
+
+/**
+ * Checks if a message is an assistant message with tool calls.
+ * @param message - Message to inspect
+ * @returns true if message has role 'assistant' and contains toolCalls array
+ */
+function hasToolCalls(message: Message): boolean {
+	return (
+		message.role === CONSTANTS.ASSISTANT_ROLE &&
+		'toolCalls' in message &&
+		Array.isArray(message.toolCalls) &&
+		message.toolCalls.length > 0
+	)
+}
+
+/**
+ * Checks if a message is a tool result message.
+ * @param message - Message to inspect
+ * @returns true if message has role 'tool'
+ */
+function isToolMessage(message: Message): boolean {
+	return message.role === CONSTANTS.TOOL_ROLE
+}
+
+/**
+ * Scans a message sequence and identifies dangling tool call/result pairs.
+ *
+ * A dangling pair occurs when:
+ * 1. An assistant message has tool calls but no matching tool message follows
+ * 2. A tool message exists but its toolCallId doesn't match any preceding assistant tool call
+ *
+ * @param messages - Array of messages to scan
+ * @returns DanglingResult with indices of invalid messages
+ *
+ * @example
+ * ```typescript
+ * const messages = [
+ *   { role: 'user', content: 'test' },
+ *   { role: 'assistant', content: null, toolCalls: [{ id: '1', type: 'function', function: { name: 'test', arguments: '{}' } }] },
+ *   // Missing tool message for call id '1'
+ *   { role: 'user', content: 'next' }
+ * ]
+ * const result = findDanglingMessages(messages)
+ * // result.assistantsWithUnmatchedCalls = [1] (index 1 has unmatched tool call)
+ * ```
+ */
+export function findDanglingMessages(messages: Message[]): DanglingResult {
+	const assistantsWithUnmatchedCalls: number[] = []
+	const orphanedToolMessages: number[] = []
+
+	// Build a set of all tool call IDs that exist in assistant messages
+	// along with their coverage map (which tool messages satisfy them)
+	const toolCallIds = new Map<string, { assistantIndex: number; satisfied: boolean }>()
+
+	for (let i = 0; i < messages.length; i++) {
+		const message = messages[i]
+		if (!message) continue
+
+		if (hasToolCalls(message)) {
+			// Record all tool calls from this assistant message
+			const assistantMsg = message as { toolCalls?: Array<{ id: string }> }
+			if (assistantMsg.toolCalls) {
+				for (const toolCall of assistantMsg.toolCalls) {
+					toolCallIds.set(toolCall.id, { assistantIndex: i, satisfied: false })
+				}
+			}
+		}
+	}
+
+	// Second pass: mark satisfied tool calls and find orphaned tool messages
+	for (let i = 0; i < messages.length; i++) {
+		const message = messages[i]
+		if (!message) continue
+
+		if (isToolMessage(message)) {
+			const toolMsg = message as { toolCallId: string }
+			if (toolCallIds.has(toolMsg.toolCallId)) {
+				// Tool message satisfies a preceding tool call
+				const entry = toolCallIds.get(toolMsg.toolCallId)
+				if (entry) {
+					entry.satisfied = true
+				}
+			} else {
+				// Tool message has no matching tool call
+				orphanedToolMessages.push(i)
+			}
+		}
+	}
+
+	// Third pass: identify unsatisfied tool calls
+	for (const entry of toolCallIds.values()) {
+		if (!entry.satisfied) {
+			assistantsWithUnmatchedCalls.push(entry.assistantIndex)
+		}
+	}
+
+	return {
+		assistantsWithUnmatchedCalls,
+		orphanedToolMessages,
+		isValid: assistantsWithUnmatchedCalls.length === 0 && orphanedToolMessages.length === 0,
+	}
+}
+
+/**
+ * Removes dangling messages from a message sequence, preserving order.
+ *
+ * This function removes the minimum set of messages needed to ensure
+ * all remaining tool call/result pairs are valid and complete.
+ *
+ * Algorithm:
+ * 1. Identify dangling assistant messages and orphaned tool messages
+ * 2. Remove orphaned tool messages
+ * 3. For assistant messages with unmatched calls, remove both the assistant
+ *    message AND any following tool messages that attempt to satisfy it
+ *
+ * @param messages - Array of messages to clean
+ * @returns New array with dangling messages removed, original order preserved
+ *
+ * @example
+ * ```typescript
+ * const messages = [
+ *   { role: 'user', content: 'test' },
+ *   { role: 'assistant', content: null, toolCalls: [{ id: '1', ... }] },
+ *   // Missing tool response
+ *   { role: 'user', content: 'next' }
+ * ]
+ * const clean = removeDanglingMessages(messages)
+ * // Result: [{ role: 'user', content: 'test' }, { role: 'user', content: 'next' }]
+ * ```
+ */
+export function removeDanglingMessages(messages: Message[]): Message[] {
+	const result = findDanglingMessages(messages)
+
+	if (result.isValid) {
+		return messages.slice() // Return shallow copy if already valid
+	}
+
+	// Build a set of indices to remove
+	const indicesToRemove = new Set<number>()
+
+	// Mark orphaned tool messages for removal
+	for (const idx of result.orphanedToolMessages) {
+		indicesToRemove.add(idx)
+	}
+
+	// For unsatisfied assistant messages:
+	// 1. Remove the assistant message itself
+	// 2. Remove any immediately following tool messages (they can't match)
+
+	for (const assistantIdx of result.assistantsWithUnmatchedCalls) {
+		indicesToRemove.add(assistantIdx)
+
+		// Collect the tool call IDs from this unsatisfied assistant message
+		const assistantMsg = messages[assistantIdx] as {
+			toolCalls?: Array<{ id: string }>
+		}
+		const toolCallIds = new Set<string>()
+		if (assistantMsg.toolCalls) {
+			for (const toolCall of assistantMsg.toolCalls) {
+				toolCallIds.add(toolCall.id)
+			}
+		}
+
+		// Remove any following tool messages that match these tool call IDs
+		// (they are orphaned now that the assistant message is removed)
+		for (let i = assistantIdx + 1; i < messages.length; i++) {
+			const msg = messages[i]
+			if (!msg) continue
+			if (isToolMessage(msg)) {
+				const toolMsg = msg as { toolCallId: string }
+				if (toolCallIds.has(toolMsg.toolCallId)) {
+					indicesToRemove.add(i)
+				}
+			}
+		}
+	}
+
+	// Return messages not marked for removal, preserving order
+	return messages.filter((_, idx) => !indicesToRemove.has(idx))
+}
+
+/**
+ * Finds a safe index for trimming messages while preserving tool call/result atomicity.
+ *
+ * Given a desired trim point (maxIndex), adjusts it forward to ensure:
+ * 1. The trim doesn't split a tool call/result pair
+ * 2. The first message after the trim point is not a ToolMessage (orphaned result)
+ * 3. All tool call/result pairs are kept intact (either fully included or fully excluded)
+ *
+ * Algorithm:
+ * 1. Start from desired index
+ * 2. Check if there's an incomplete tool call/result pair that started before the trim point
+ * 3. If so, advance trim point past the complete pair
+ * 4. If the new trim point starts with a tool message, advance past it
+ *
+ * @param messages - Array of messages to analyze
+ * @param targetIndex - Desired trim point (exclusive upper bound)
+ * @returns Safe trim index where message sequence is valid (at least 0, at most messages.length)
+ *
+ * @example
+ * ```typescript
+ * const messages = [
+ *   { role: 'user', content: 'test' },
+ *   { role: 'assistant', content: null, toolCalls: [{ id: '1', ... }] },
+ *   { role: 'tool', content: 'result', toolCallId: '1' },
+ *   { role: 'user', content: 'next' }
+ * ]
+ * const safeIdx = findSafeTrimIndex(messages, 2)
+ * // Result: 3 (skips the incomplete pair at index 1-2)
+ * ```
+ */
+export function findSafeTrimIndex(messages: Message[], targetIndex: number): number {
+	// Clamp to valid bounds
+	const clampedTarget = Math.max(0, Math.min(targetIndex, messages.length))
+
+	// If no messages after trim point, safe to trim here
+	if (clampedTarget >= messages.length) {
+		return messages.length
+	}
+
+	// Check for incomplete tool call/result pairs that cross the trim boundary
+	// Build a map of tool call IDs and whether they have results in the kept portion
+	let currentIndex = clampedTarget
+	let attempts = 0
+	const maxAttempts = messages.length // Prevent infinite loops
+
+	while (attempts < maxAttempts) {
+		attempts++
+
+		if (currentIndex >= messages.length) {
+			break
+		}
+
+		// Check if message at currentIndex is a tool message (orphaned result)
+		const currentMsg = messages[currentIndex]
+		if (currentMsg && isToolMessage(currentMsg)) {
+			// Skip orphaned tool message
+			currentIndex++
+			continue
+		}
+
+		// Check for incomplete tool call/result pairs in the kept portion [0, currentIndex)
+		const keptMessages = messages.slice(0, currentIndex)
+		const incompleteResult = findDanglingMessages(keptMessages)
+
+		if (!incompleteResult.isValid) {
+			// Find the maximum dangling message index
+			const allDanglingIndices = [
+				...incompleteResult.assistantsWithUnmatchedCalls,
+				...incompleteResult.orphanedToolMessages,
+			]
+
+			if (allDanglingIndices.length === 0) {
+				// No dangling messages found, but isValid is false — shouldn't happen
+				break
+			}
+
+			const maxDanglingIdx = Math.max(...allDanglingIndices)
+
+			// Move trim point past the dangling message
+			currentIndex = maxDanglingIdx + 1
+
+			// For assistant messages, also skip following tool messages from that call
+			const assistantAtDanglingIdx = messages[maxDanglingIdx]
+			if (assistantAtDanglingIdx && hasToolCalls(assistantAtDanglingIdx)) {
+				const toolCallIds = new Set<string>()
+				const assistantMsg = assistantAtDanglingIdx as {
+					toolCalls?: Array<{ id: string }>
+				}
+				if (assistantMsg.toolCalls) {
+					for (const toolCall of assistantMsg.toolCalls) {
+						toolCallIds.add(toolCall.id)
+					}
+				}
+
+				// Skip following tool messages from this assistant
+				while (currentIndex < messages.length) {
+					const nextMsg = messages[currentIndex]
+					if (!nextMsg) break
+					if (isToolMessage(nextMsg)) {
+						const toolMsg = nextMsg as { toolCallId: string }
+						if (toolCallIds.has(toolMsg.toolCallId)) {
+							currentIndex++
+							continue
+						}
+					}
+					break
+				}
+			}
+		} else {
+			// No dangling messages in the kept portion, we're safe
+			break
+		}
+	}
+
+	return Math.min(currentIndex, messages.length)
+}

package/src/compaction/factory.ts

@@ -0,0 +1,41 @@
+import type { CompactionConfig } from '../config/runtime.js'
+import type { ConversationManager } from './interface.js'
+import { NullManager } from './managers/null.js'
+import { SlidingWindowManager } from './managers/slidingWindow.js'
+import { StructuredCompactionManager } from './managers/structured.js'
+import type { CompactionStrategy } from './types.js'
+
+/**
+ * Factory function to create a ConversationManager based on the configured strategy.
+ *
+ * @param strategy - Selected compaction strategy: 'structured', 'sliding-window', or 'disabled'
+ * @param config - CompactionConfig with keepRecentMessages and other settings
+ * @returns Instantiated ConversationManager
+ *
+ * @throws If strategy is not recognized (exhaustiveness check ensures this never happens at runtime)
+ *
+ * @example
+ * ```typescript
+ * const manager = createConversationManager('structured', config)
+ * const trimmed = manager.applyManagement(messages)
+ * ```
+ */
+export function createConversationManager(
+	strategy: CompactionStrategy,
+	config: CompactionConfig,
+): ConversationManager {
+	switch (strategy) {
+		case 'structured':
+			return new StructuredCompactionManager(config)
+		case 'sliding-window':
+			return new SlidingWindowManager({
+				keepRecentMessages: config.keepRecentMessages,
+			})
+		case 'disabled':
+			return new NullManager()
+		default: {
+			const _exhaustive: never = strategy
+			throw new Error(`Unknown compaction strategy: ${_exhaustive}`)
+		}
+	}
+}

package/src/compaction/index.ts

@@ -7,6 +7,10 @@ export type {
 	CompactionStrategy,
 } from './types.js'
 
+export type { DanglingResult } from './dangling.js'
+
+export type { ConversationManager } from './interface.js'
+
 export { WorkingStateManager } from './manager.js'
 
 export { serializeState } from './serializer.js'
@@ -19,3 +23,13 @@ export {
 } from './extractor.js'
 
 export { buildVerifiedSummary } from './verifier.js'
+
+export {
+	findDanglingMessages,
+	removeDanglingMessages,
+	findSafeTrimIndex,
+} from './dangling.js'
+
+export { NullManager, SlidingWindowManager, StructuredCompactionManager } from './managers/index.js'
+
+export { createConversationManager } from './factory.js'

package/src/compaction/interface.ts

@@ -0,0 +1,35 @@
+import type { Message } from '../types/message/index.js'
+
+/**
+ * Strategy interface for managing conversation context.
+ * Implementations decide how to handle context overflow and message trimming.
+ *
+ * A manager applies two strategies:
+ * 1. **Routine management** (applyManagement): Called after each iteration to proactively optimize context.
+ * 2. **Overflow reduction** (reduceContext): Called when the LLM reports context window exceeded.
+ */
+export interface ConversationManager {
+	/** Unique name for this manager (e.g., 'structured', 'sliding-window', 'disabled') */
+	readonly name: string
+
+	/**
+	 * Apply routine management after each iteration.
+	 * Called proactively, not in response to an error.
+	 * Returns modified messages array (or same reference if no changes).
+	 *
+	 * @param messages - Current message history
+	 * @returns Modified messages array (may be same reference if no changes made)
+	 */
+	applyManagement(messages: Message[]): Message[]
+
+	/**
+	 * Reduce context when overflow is detected.
+	 * Called when the LLM reports context window exceeded.
+	 * Returns true if context was successfully reduced, false if no reduction possible.
+	 *
+	 * @param messages - Current message history
+	 * @param overflowTokens - Approximate number of tokens over budget
+	 * @returns true if context was successfully reduced, false if no reduction possible
+	 */
+	reduceContext(messages: Message[], overflowTokens: number): boolean
+}

package/src/compaction/managers/index.ts

@@ -0,0 +1,3 @@
+export { NullManager } from './null.js'
+export { SlidingWindowManager, type SlidingWindowManagerConfig } from './slidingWindow.js'
+export { StructuredCompactionManager } from './structured.js'

package/src/compaction/managers/null.ts

@@ -0,0 +1,19 @@
+import type { Message } from '../../types/message/index.js'
+import type { ConversationManager } from '../interface.js'
+
+/**
+ * No-op conversation manager implementation.
+ * Never modifies messages, useful for testing or when context management is disabled.
+ */
+export class NullManager implements ConversationManager {
+	readonly name = 'null'
+
+	applyManagement(messages: Message[]): Message[] {
+		return messages
+	}
+
+	reduceContext(_messages: Message[], _overflowTokens: number): boolean {
+		// Cannot reduce; no operations performed
+		return false
+	}
+}

package/src/compaction/managers/slidingWindow.ts

@@ -0,0 +1,57 @@
+import type { Message } from '../../types/message/index.js'
+import { findSafeTrimIndex } from '../dangling.js'
+import type { ConversationManager } from '../interface.js'
+
+export interface SlidingWindowManagerConfig {
+	/**
+	 * Number of most recent messages to always keep.
+	 * Default: 4
+	 */
+	keepRecentMessages?: number
+}
+
+/**
+ * Simple window-based conversation manager.
+ * Trims old messages to maintain a fixed-size window of recent context.
+ * Fastest strategy, least context preservation.
+ *
+ * Algorithm:
+ * 1. If message count exceeds window size, trim excess from the start
+ * 2. Use findSafeTrimIndex to ensure tool call/result pairs remain atomic
+ * 3. applyManagement runs proactively each iteration; reduceContext on overflow
+ */
+export class SlidingWindowManager implements ConversationManager {
+	readonly name = 'sliding-window'
+	private readonly keepRecentMessages: number
+
+	constructor(config: SlidingWindowManagerConfig = {}) {
+		this.keepRecentMessages = config.keepRecentMessages ?? 4
+	}
+
+	applyManagement(messages: Message[]): Message[] {
+		// Trim to window size if needed
+		if (messages.length <= this.keepRecentMessages) {
+			return messages
+		}
+
+		const desiredTrimPoint = messages.length - this.keepRecentMessages
+		const safeTrimIdx = findSafeTrimIndex(messages, desiredTrimPoint)
+		return messages.slice(safeTrimIdx)
+	}
+
+	reduceContext(messages: Message[], _overflowTokens: number): boolean {
+		// Try to reduce by trimming more aggressively
+		// Target: keep even fewer messages than normal window
+		const targetWindow = Math.max(1, Math.floor(this.keepRecentMessages * 0.5))
+		const desiredTrimPoint = messages.length - targetWindow
+		const safeTrimIdx = findSafeTrimIndex(messages, desiredTrimPoint)
+
+		if (safeTrimIdx >= messages.length) {
+			// Cannot trim further
+			return false
+		}
+
+		// Successfully trimmed if we removed at least one message
+		return safeTrimIdx > 0
+	}
+}

package/src/compaction/managers/structured.ts

@@ -0,0 +1,169 @@
+import type { CompactionConfig } from '../../config/runtime.js'
+import type { Message } from '../../types/message/index.js'
+import { findSafeTrimIndex } from '../dangling.js'
+import {
+	extractFromAssistantMessage,
+	extractFromToolCall,
+	extractFromUserMessage,
+} from '../extractor.js'
+import type { ConversationManager } from '../interface.js'
+import { WorkingStateManager } from '../manager.js'
+import { serializeState } from '../serializer.js'
+
+/**
+ * Structured conversation manager wrapping the existing WorkingStateManager.
+ * Extracts context from messages into a structured state, then compacts via serialization.
+ *
+ * Flow:
+ * 1. Extract state from input messages (tracks tasks, decisions, files, etc.)
+ * 2. Serialize state to XML-like format
+ * 3. Inject compacted state as system message
+ * 4. Trim older messages, keeping the state message + recent history
+ *
+ * Provides maximum context preservation but more computational overhead.
+ */
+export class StructuredCompactionManager implements ConversationManager {
+	readonly name = 'structured'
+	private readonly config: CompactionConfig
+
+	constructor(config: CompactionConfig) {
+		this.config = config
+	}
+
+	applyManagement(messages: Message[]): Message[] {
+		// Build working state from all messages
+		const stateManager = new WorkingStateManager(this.config)
+
+		let isFirstUserMessage = true
+		for (const message of messages) {
+			if (message.role === 'user') {
+				extractFromUserMessage(stateManager, message.content, isFirstUserMessage)
+				isFirstUserMessage = false
+			} else if (message.role === 'assistant' && message.content) {
+				extractFromAssistantMessage(stateManager, message.content, this.config)
+			} else if (message.role === 'tool') {
+				// Extract from tool messages if needed (optional refinement)
+				// For now, we focus on assistant and user content
+			} else if (message.role === 'assistant' && 'toolCalls' in message && message.toolCalls) {
+				// Extract from tool calls
+				for (const toolCall of message.toolCalls) {
+					extractFromToolCall(stateManager, toolCall.function.name, toolCall.function.arguments)
+				}
+			}
+		}
+
+		// If not much context accumulated, don't inject state yet
+		if (stateManager.slotCount() < this.config.richStateThreshold) {
+			return messages
+		}
+
+		// Serialize state to string
+		const state = stateManager.getState()
+		const serialized = serializeState(state)
+
+		// Inject as system message at the start (after first user message if present)
+		const result: Message[] = []
+		let injected = false
+
+		for (let i = 0; i < messages.length; i++) {
+			const msg = messages[i]
+			if (!msg) continue
+
+			// Keep system messages and first user message
+			result.push(msg)
+
+			// Inject after first user message
+			if (!injected && msg.role === 'user') {
+				result.push({
+					role: 'system',
+					content: serialized,
+					timestamp: Date.now(),
+				})
+				injected = true
+			}
+		}
+
+		// If no user message found, inject at start
+		if (!injected) {
+			result.unshift({
+				role: 'system',
+				content: serialized,
+				timestamp: Date.now(),
+			})
+		}
+
+		// Trim old messages while keeping state message
+		if (result.length > this.config.keepRecentMessages + 2) {
+			const desiredTrimPoint = result.length - this.config.keepRecentMessages
+			const safeTrimIdx = findSafeTrimIndex(result, desiredTrimPoint)
+
+			// Always keep the injected system message
+			const trimPoint = Math.min(
+				safeTrimIdx,
+				Math.max(0, result.length - this.config.keepRecentMessages),
+			)
+			return result.slice(trimPoint)
+		}
+
+		return result
+	}
+
+	reduceContext(messages: Message[], _overflowTokens: number): boolean {
+		// Use the same approach as applyManagement but more aggressive trimming
+		const stateManager = new WorkingStateManager(this.config)
+
+		let isFirstUserMessage = true
+		for (const message of messages) {
+			if (message.role === 'user') {
+				extractFromUserMessage(stateManager, message.content, isFirstUserMessage)
+				isFirstUserMessage = false
+			} else if (message.role === 'assistant' && message.content) {
+				extractFromAssistantMessage(stateManager, message.content, this.config)
+			} else if (message.role === 'assistant' && 'toolCalls' in message && message.toolCalls) {
+				for (const toolCall of message.toolCalls) {
+					extractFromToolCall(stateManager, toolCall.function.name, toolCall.function.arguments)
+				}
+			}
+		}
+
+		const state = stateManager.getState()
+		const serialized = serializeState(state)
+
+		// Build new messages: keep system messages, inject state, keep fewer recent messages
+		const result: Message[] = []
+		let injected = false
+
+		for (const msg of messages) {
+			if (msg.role === 'system') {
+				result.push(msg)
+			} else if (!injected && msg.role === 'user') {
+				result.push(msg)
+				result.push({
+					role: 'system',
+					content: serialized,
+					timestamp: Date.now(),
+				})
+				injected = true
+			}
+		}
+
+		// Add recent messages
+		const recentCount = Math.max(1, Math.floor(this.config.keepRecentMessages * 0.5))
+		const recentMessages = messages.filter((m) => m.role !== 'system').slice(-recentCount)
+
+		for (const msg of recentMessages) {
+			if (!result.includes(msg)) {
+				result.push(msg)
+			}
+		}
+
+		// Use safe trim to preserve tool atomicity
+		if (result.length > recentCount + 2) {
+			const desiredTrimPoint = result.length - recentCount
+			const safeTrimIdx = findSafeTrimIndex(result, desiredTrimPoint)
+			return safeTrimIdx > 0 && safeTrimIdx < result.length
+		}
+
+		return result.length < messages.length
+	}
+}

package/src/compaction/types.ts

@@ -34,4 +34,4 @@ export interface ToolResultSlot {
 	timestamp: number
 }
 
-export type CompactionStrategy = 'structured' | 'disabled'
+export type CompactionStrategy = 'structured' | 'sliding-window' | 'disabled'

package/src/config/runtime.ts

@@ -17,7 +17,7 @@ export const TaskRouterConfigSchema = z
 	.optional()
 
 export const CompactionConfigSchema = z.object({
-	strategy: z.enum(['structured', 'disabled']).default('structured'),
+	strategy: z.enum(['structured', 'sliding-window', 'disabled']).default('structured'),
 	triggerThreshold: z.number().min(0).max(1).default(0.7),
 	resetThreshold: z.number().min(0).max(1).default(0.4),
 	keepRecentMessages: z.number().positive().default(4),