recursive-llm-ts 4.8.0 → 5.0.0

package/go/rlm/lcm_context_loop.go

@@ -0,0 +1,309 @@
+package rlm
+
+import (
+	"fmt"
+	"sync"
+)
+
+// ─── LCM Context Control Loop ───────────────────────────────────────────────
+// Implements the dual-threshold context management from the LCM paper:
+// - Below τ_soft: no overhead (zero-cost continuity)
+// - τ_soft ≤ tokens < τ_hard: async compaction between turns
+// - tokens ≥ τ_hard: blocking compaction before next LLM call
+
+// LCMConfig configures the Lossless Context Management engine.
+type LCMConfig struct {
+	// Enabled activates LCM context management (default: false for backward compat)
+	Enabled bool `json:"enabled"`
+
+	// SoftThreshold is τ_soft: token count above which async compaction begins.
+	// Default: 70% of model limit.
+	SoftThreshold int `json:"soft_threshold,omitempty"`
+
+	// HardThreshold is τ_hard: token count above which blocking compaction occurs.
+	// Default: 90% of model limit.
+	HardThreshold int `json:"hard_threshold,omitempty"`
+
+	// CompactionBlockSize is how many messages to compact at once.
+	// Default: 10 messages.
+	CompactionBlockSize int `json:"compaction_block_size,omitempty"`
+
+	// SummaryTargetTokens is the target size for each summary node.
+	// Default: 500 tokens.
+	SummaryTargetTokens int `json:"summary_target_tokens,omitempty"`
+}
+
+// DefaultLCMConfig returns default LCM configuration.
+func DefaultLCMConfig() LCMConfig {
+	return LCMConfig{
+		Enabled:             false,
+		CompactionBlockSize: 10,
+		SummaryTargetTokens: 500,
+	}
+}
+
+// LCMEngine is the main LCM context management engine.
+// It wraps the store, summarizer, and context control loop.
+type LCMEngine struct {
+	config     LCMConfig
+	store      *LCMStore
+	summarizer *LCMSummarizer
+	observer   *Observer
+	modelLimit int
+
+	// Async compaction state
+	compactMu     sync.Mutex
+	compacting    bool
+	compactResult chan *compactionResult
+}
+
+type compactionResult struct {
+	summary *SummaryNode
+	err     error
+}
+
+// NewLCMEngine creates a new LCM engine with the given configuration.
+func NewLCMEngine(config LCMConfig, store *LCMStore, summarizer *LCMSummarizer, observer *Observer, modelLimit int) *LCMEngine {
+	// Apply defaults based on model limit
+	if config.SoftThreshold == 0 && modelLimit > 0 {
+		config.SoftThreshold = int(float64(modelLimit) * 0.70)
+	}
+	if config.HardThreshold == 0 && modelLimit > 0 {
+		config.HardThreshold = int(float64(modelLimit) * 0.90)
+	}
+	if config.CompactionBlockSize == 0 {
+		config.CompactionBlockSize = 10
+	}
+	if config.SummaryTargetTokens == 0 {
+		config.SummaryTargetTokens = 500
+	}
+
+	return &LCMEngine{
+		config:     config,
+		store:      store,
+		summarizer: summarizer,
+		observer:   observer,
+		modelLimit: modelLimit,
+	}
+}
+
+// ─── Context Control Loop (Algorithm 2 from paper) ──────────────────────────
+
+// OnNewItem is called after each new message is added to the store.
+// It implements the context control loop from Figure 2 of the LCM paper.
+// Returns nil if no compaction was needed or if async compaction was triggered.
+func (e *LCMEngine) OnNewItem() error {
+	if !e.config.Enabled {
+		return nil
+	}
+
+	// Check if async compaction has completed
+	e.applyPendingCompaction()
+
+	tokens := e.store.ActiveContextTokens()
+
+	// Below soft threshold: zero-cost continuity
+	if tokens <= e.config.SoftThreshold {
+		return nil
+	}
+
+	// Soft threshold exceeded: trigger async compaction (non-blocking)
+	if tokens < e.config.HardThreshold {
+		e.observer.Debug("lcm.control", "Soft threshold exceeded (%d > %d), triggering async compaction",
+			tokens, e.config.SoftThreshold)
+		e.triggerAsyncCompaction()
+		return nil
+	}
+
+	// Hard threshold exceeded: blocking compaction
+	e.observer.Debug("lcm.control", "Hard threshold exceeded (%d >= %d), blocking compaction",
+		tokens, e.config.HardThreshold)
+	return e.blockingCompaction()
+}
+
+// ─── Async Compaction ───────────────────────────────────────────────────────
+
+func (e *LCMEngine) triggerAsyncCompaction() {
+	e.compactMu.Lock()
+	if e.compacting {
+		e.compactMu.Unlock()
+		return // Already compacting
+	}
+	e.compacting = true
+	e.compactResult = make(chan *compactionResult, 1)
+	e.compactMu.Unlock()
+
+	go func() {
+		result := e.performCompaction()
+		e.compactResult <- result
+	}()
+}
+
+func (e *LCMEngine) applyPendingCompaction() {
+	e.compactMu.Lock()
+	if !e.compacting || e.compactResult == nil {
+		e.compactMu.Unlock()
+		return
+	}
+
+	// Non-blocking check
+	select {
+	case result := <-e.compactResult:
+		e.compacting = false
+		e.compactMu.Unlock()
+
+		if result.err != nil {
+			e.observer.Error("lcm.control", "Async compaction failed: %v", result.err)
+			return
+		}
+		if result.summary != nil {
+			removed := e.store.CompactOldestBlock(result.summary)
+			e.observer.Debug("lcm.control", "Async compaction applied: replaced %d messages with summary %s",
+				len(removed), result.summary.ID)
+			e.observer.Event("lcm.compaction", map[string]string{
+				"type":           "async",
+				"summary_id":     result.summary.ID,
+				"messages_compacted": fmt.Sprintf("%d", len(removed)),
+				"summary_tokens": fmt.Sprintf("%d", result.summary.Tokens),
+				"level":          fmt.Sprintf("%d", result.summary.Level),
+			})
+		}
+	default:
+		e.compactMu.Unlock()
+		// Not done yet, continue
+	}
+}
+
+// ─── Blocking Compaction ────────────────────────────────────────────────────
+
+func (e *LCMEngine) blockingCompaction() error {
+	// Keep compacting until under hard threshold
+	for e.store.ActiveContextTokens() >= e.config.HardThreshold {
+		result := e.performCompaction()
+		if result.err != nil {
+			return fmt.Errorf("blocking compaction failed: %w", result.err)
+		}
+		if result.summary == nil {
+			break // Nothing more to compact
+		}
+
+		removed := e.store.CompactOldestBlock(result.summary)
+		e.observer.Debug("lcm.control", "Blocking compaction: replaced %d messages with summary %s (%d tokens)",
+			len(removed), result.summary.ID, result.summary.Tokens)
+		e.observer.Event("lcm.compaction", map[string]string{
+			"type":               "blocking",
+			"summary_id":         result.summary.ID,
+			"messages_compacted": fmt.Sprintf("%d", len(removed)),
+			"summary_tokens":     fmt.Sprintf("%d", result.summary.Tokens),
+			"level":              fmt.Sprintf("%d", result.summary.Level),
+		})
+	}
+	return nil
+}
+
+// ─── Core Compaction ────────────────────────────────────────────────────────
+
+func (e *LCMEngine) performCompaction() *compactionResult {
+	active := e.store.GetActiveContext()
+
+	// Find the oldest block of raw messages to compact (skip system prompt)
+	var block []*StoreMessage
+	for _, item := range active {
+		if item.IsMessage() {
+			if item.Message.Role == RoleSystem {
+				continue // Never compact system prompt
+			}
+			block = append(block, item.Message)
+			if len(block) >= e.config.CompactionBlockSize {
+				break
+			}
+		}
+	}
+
+	if len(block) == 0 {
+		return &compactionResult{summary: nil, err: nil}
+	}
+
+	// Apply three-level escalation
+	result, err := e.summarizer.SummarizeMessages(block, e.config.SummaryTargetTokens)
+	if err != nil {
+		return &compactionResult{err: err}
+	}
+
+	// Create summary node in the DAG
+	var msgIDs []string
+	for _, msg := range block {
+		msgIDs = append(msgIDs, msg.ID)
+	}
+
+	summary := e.store.CreateLeafSummary(msgIDs, result.Content, result.Level)
+
+	return &compactionResult{summary: summary}
+}
+
+// ─── Condensed Summaries (DAG depth > 1) ────────────────────────────────────
+
+// CondenseOldSummaries finds summary nodes in the active context and merges them
+// into a higher-order condensed summary. This creates DAG depth > 1.
+func (e *LCMEngine) CondenseOldSummaries() error {
+	active := e.store.GetActiveContext()
+
+	// Collect summary items
+	var summaryItems []*ActiveContextItem
+	for _, item := range active {
+		if !item.IsMessage() && item.Summary != nil {
+			summaryItems = append(summaryItems, item)
+		}
+	}
+
+	// Need at least 2 summaries to condense
+	if len(summaryItems) < 2 {
+		return nil
+	}
+
+	// Condense the oldest summaries
+	condenseCount := len(summaryItems)
+	if condenseCount > e.config.CompactionBlockSize {
+		condenseCount = e.config.CompactionBlockSize
+	}
+	toCondense := summaryItems[:condenseCount]
+
+	// Build combined content for re-summarization
+	var combined string
+	var childIDs []string
+	for _, item := range toCondense {
+		combined += item.Summary.Content + "\n\n"
+		childIDs = append(childIDs, item.Summary.ID)
+	}
+
+	// Summarize the combined summaries
+	result, err := e.summarizer.Summarize(combined, e.config.SummaryTargetTokens)
+	if err != nil {
+		return fmt.Errorf("condensation failed: %w", err)
+	}
+
+	// Create condensed summary node
+	condensed := e.store.CreateCondensedSummary(childIDs, result.Content, result.Level)
+
+	e.observer.Debug("lcm.control", "Condensed %d summaries into %s (%d tokens)",
+		len(childIDs), condensed.ID, condensed.Tokens)
+
+	return nil
+}
+
+// ─── Query Helpers ──────────────────────────────────────────────────────────
+
+// GetStore returns the underlying LCM store.
+func (e *LCMEngine) GetStore() *LCMStore {
+	return e.store
+}
+
+// GetConfig returns the LCM configuration.
+func (e *LCMEngine) GetConfig() LCMConfig {
+	return e.config
+}
+
+// IsEnabled returns whether LCM is active.
+func (e *LCMEngine) IsEnabled() bool {
+	return e.config.Enabled
+}

package/go/rlm/lcm_delegation.go

@@ -0,0 +1,257 @@
+package rlm
+
+import (
+	"fmt"
+	"strings"
+)
+
+// ─── Infinite Delegation Guard ──────────────────────────────────────────────
+// Implements the scope-reduction invariant from the LCM paper (Section 3.2).
+//
+// When a sub-agent spawns a further sub-agent, it must declare:
+//   - delegated_scope: the specific slice of work being handed off
+//   - kept_work: the work the caller will still perform itself
+//
+// If the caller cannot articulate what it's retaining (i.e., it would delegate
+// its entire responsibility), the call is rejected. This forces each level of
+// delegation to represent a strict reduction in responsibility.
+//
+// Exemptions:
+//   - Root agent (depth 0): no parent to recurse with
+//   - Read-only agents: cannot spawn further sub-agents
+//   - Parallel decomposition (sibling tasks): not nested delegation
+
+// DelegationRequest represents a request to delegate work to a sub-agent.
+type DelegationRequest struct {
+	// Prompt is the task description for the sub-agent.
+	Prompt string `json:"prompt"`
+
+	// DelegatedScope describes the specific slice of work being handed off.
+	// Required for non-root agents.
+	DelegatedScope string `json:"delegated_scope"`
+
+	// KeptWork describes the work the caller retains for itself.
+	// Required for non-root agents. Must be non-empty and distinct from DelegatedScope.
+	KeptWork string `json:"kept_work"`
+
+	// ReadOnly indicates this is a read-only exploration agent (exempt from guard).
+	ReadOnly bool `json:"read_only"`
+
+	// Parallel indicates this is parallel decomposition (exempt from guard).
+	Parallel bool `json:"parallel"`
+}
+
+// DelegationGuard enforces the scope-reduction invariant.
+type DelegationGuard struct {
+	observer *Observer
+}
+
+// NewDelegationGuard creates a new delegation guard.
+func NewDelegationGuard(observer *Observer) *DelegationGuard {
+	return &DelegationGuard{observer: observer}
+}
+
+// DelegationError is returned when a delegation request violates the scope-reduction invariant.
+type DelegationError struct {
+	Reason     string `json:"reason"`
+	Suggestion string `json:"suggestion"`
+}
+
+func (e *DelegationError) Error() string {
+	return fmt.Sprintf("delegation rejected: %s. %s", e.Reason, e.Suggestion)
+}
+
+// ValidateDelegation checks if a delegation request is allowed at the given depth.
+// Returns nil if allowed, or a DelegationError explaining why it was rejected.
+func (g *DelegationGuard) ValidateDelegation(depth int, req DelegationRequest) error {
+	// Root agent (depth 0) is always allowed to delegate
+	if depth == 0 {
+		g.observer.Debug("lcm.delegation", "Root agent delegation allowed (depth 0)")
+		return nil
+	}
+
+	// Read-only agents are exempt (they can't spawn further sub-agents)
+	if req.ReadOnly {
+		g.observer.Debug("lcm.delegation", "Read-only agent delegation allowed")
+		return nil
+	}
+
+	// Parallel decomposition is exempt (sibling, not nested)
+	if req.Parallel {
+		g.observer.Debug("lcm.delegation", "Parallel decomposition delegation allowed")
+		return nil
+	}
+
+	// Non-root agents must declare scope reduction
+	if strings.TrimSpace(req.DelegatedScope) == "" {
+		g.observer.Debug("lcm.delegation", "Delegation rejected: no delegated_scope at depth %d", depth)
+		return &DelegationError{
+			Reason:     "sub-agent must declare delegated_scope",
+			Suggestion: "Describe the specific slice of work being handed off, or perform the work directly.",
+		}
+	}
+
+	if strings.TrimSpace(req.KeptWork) == "" {
+		g.observer.Debug("lcm.delegation", "Delegation rejected: no kept_work at depth %d", depth)
+		return &DelegationError{
+			Reason:     "sub-agent must declare kept_work (what the caller retains)",
+			Suggestion: "If you cannot articulate what you're retaining, perform the work directly instead of delegating.",
+		}
+	}
+
+	// Check for full delegation (delegated_scope ≈ entire task)
+	if isTotalDelegation(req.DelegatedScope, req.KeptWork) {
+		g.observer.Debug("lcm.delegation", "Delegation rejected: total delegation detected at depth %d", depth)
+		return &DelegationError{
+			Reason:     "delegated_scope appears to encompass the entire task; kept_work is trivial",
+			Suggestion: "Break the task into meaningful subtasks where you retain substantial work, or perform it directly.",
+		}
+	}
+
+	g.observer.Debug("lcm.delegation", "Delegation allowed at depth %d: scope=%q, kept=%q",
+		depth, truncateStr(req.DelegatedScope, 80), truncateStr(req.KeptWork, 80))
+	return nil
+}
+
+// isTotalDelegation detects when an agent is trying to delegate its entire responsibility.
+// This is a heuristic check — it catches obvious cases of trivial kept_work.
+func isTotalDelegation(delegatedScope, keptWork string) bool {
+	kept := strings.TrimSpace(strings.ToLower(keptWork))
+
+	// Trivial kept_work patterns that indicate full delegation
+	trivialPatterns := []string{
+		"none",
+		"nothing",
+		"n/a",
+		"na",
+		"",
+		"will wait",
+		"waiting",
+		"just wait",
+		"aggregate",
+		"collect results",
+		"return results",
+		"pass through",
+		"forward",
+	}
+
+	for _, pattern := range trivialPatterns {
+		if kept == pattern {
+			return true
+		}
+	}
+
+	// Check if kept_work is suspiciously short compared to delegated_scope
+	// (less than 10% of the delegated scope's length and under 20 chars)
+	if len(kept) < 20 && len(kept) < len(delegatedScope)/10 {
+		return true
+	}
+
+	return false
+}
+
+// ─── Integration with RLM Engine ────────────────────────────────────────────
+
+// DelegateTask validates and executes a delegation request through the RLM engine.
+// This is the main entry point for task delegation with the infinite recursion guard.
+func (r *RLM) DelegateTask(req DelegationRequest) (string, RLMStats, error) {
+	// Create or use existing delegation guard
+	guard := NewDelegationGuard(r.observer)
+
+	// Validate the delegation
+	if err := guard.ValidateDelegation(r.currentDepth, req); err != nil {
+		return "", RLMStats{}, err
+	}
+
+	// Create sub-agent
+	subConfig := Config{
+		RecursiveModel:   r.recursiveModel,
+		APIBase:          r.apiBase,
+		APIKey:           r.apiKey,
+		MaxDepth:         r.maxDepth,
+		MaxIterations:    r.maxIterations,
+		TimeoutSeconds:   r.timeoutSeconds,
+		UseMetacognitive: r.useMetacognitive,
+		ExtraParams:      r.extraParams,
+	}
+
+	subRLM := New(r.recursiveModel, subConfig)
+	subRLM.currentDepth = r.currentDepth + 1
+	subRLM.observer = r.observer
+	defer subRLM.Shutdown()
+
+	r.observer.Debug("lcm.delegation", "Spawning sub-agent at depth %d for: %s",
+		r.currentDepth+1, truncateStr(req.Prompt, 100))
+
+	result, stats, err := subRLM.Completion(req.Prompt, "")
+	return result, stats, err
+}
+
+// DelegateTasks validates and executes multiple parallel delegation requests.
+// This implements the Tasks() tool from the LCM paper (Appendix C.3).
+// Parallel decomposition is exempt from the recursion guard.
+func (r *RLM) DelegateTasks(tasks []DelegationRequest) ([]string, []RLMStats, error) {
+	if len(tasks) < 2 {
+		return nil, nil, fmt.Errorf("DelegateTasks requires at least 2 tasks for parallel decomposition")
+	}
+
+	guard := NewDelegationGuard(r.observer)
+
+	// Mark all as parallel (exempt from guard) but still validate basic structure
+	for i := range tasks {
+		tasks[i].Parallel = true
+		if err := guard.ValidateDelegation(r.currentDepth, tasks[i]); err != nil {
+			return nil, nil, fmt.Errorf("task %d validation failed: %w", i, err)
+		}
+	}
+
+	r.observer.Debug("lcm.delegation", "Spawning %d parallel sub-agents at depth %d",
+		len(tasks), r.currentDepth+1)
+
+	type taskResult struct {
+		index  int
+		result string
+		stats  RLMStats
+		err    error
+	}
+
+	results := make(chan taskResult, len(tasks))
+
+	for i, task := range tasks {
+		go func(idx int, t DelegationRequest) {
+			subConfig := Config{
+				RecursiveModel:   r.recursiveModel,
+				APIBase:          r.apiBase,
+				APIKey:           r.apiKey,
+				MaxDepth:         r.maxDepth,
+				MaxIterations:    r.maxIterations,
+				TimeoutSeconds:   r.timeoutSeconds,
+				UseMetacognitive: r.useMetacognitive,
+				ExtraParams:      r.extraParams,
+			}
+
+			subRLM := New(r.recursiveModel, subConfig)
+			subRLM.currentDepth = r.currentDepth + 1
+			subRLM.observer = r.observer
+			defer subRLM.Shutdown()
+
+			result, stats, err := subRLM.Completion(t.Prompt, "")
+			results <- taskResult{index: idx, result: result, stats: stats, err: err}
+		}(i, task)
+	}
+
+	// Collect results in order
+	resultSlice := make([]string, len(tasks))
+	statsSlice := make([]RLMStats, len(tasks))
+
+	for range tasks {
+		tr := <-results
+		if tr.err != nil {
+			return nil, nil, fmt.Errorf("parallel task %d failed: %w", tr.index, tr.err)
+		}
+		resultSlice[tr.index] = tr.result
+		statsSlice[tr.index] = tr.stats
+	}
+
+	return resultSlice, statsSlice, nil
+}