recursive-llm-ts 4.9.0 → 5.0.0

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
+}

package/go/rlm/lcm_episodes.go

@@ -0,0 +1,313 @@
+package rlm
+
+import (
+	"fmt"
+	"strings"
+	"sync"
+	"time"
+)
+
+// EpisodeStatus describes lifecycle state for an episode.
+type EpisodeStatus string
+
+const (
+	// EpisodeActive is currently accumulating messages.
+	EpisodeActive EpisodeStatus = "active"
+	// EpisodeCompacted has a generated summary while messages remain available.
+	EpisodeCompacted EpisodeStatus = "compacted"
+	// EpisodeArchived is deeply compressed and represented by summary in active context.
+	EpisodeArchived EpisodeStatus = "archived"
+)
+
+// Episode is a coherent interaction unit that groups related messages.
+type Episode struct {
+	ID              string        `json:"id"`
+	Title           string        `json:"title"`
+	MessageIDs      []string      `json:"message_ids"`
+	StartTime       time.Time     `json:"start_time"`
+	EndTime         time.Time     `json:"end_time"`
+	Tokens          int           `json:"tokens"`
+	Summary         string        `json:"summary,omitempty"`
+	SummaryTokens   int           `json:"summary_tokens,omitempty"`
+	Status          EpisodeStatus `json:"status"`
+	Tags            []string      `json:"tags,omitempty"`
+	ParentEpisodeID string        `json:"parent_episode_id,omitempty"`
+}
+
+// EpisodeConfig controls episode boundaries and behavior.
+type EpisodeConfig struct {
+	MaxEpisodeTokens      int
+	MaxEpisodeMessages    int
+	TopicChangeThreshold  float64
+	AutoCompactAfterClose bool
+}
+
+// EpisodeManager manages episode creation, compaction, and retrieval.
+type EpisodeManager struct {
+	mu            sync.RWMutex
+	episodes      map[string]*Episode
+	episodeSeq    []*Episode
+	activeEpisode *Episode
+	nextID        int
+	sessionID     string
+	config        EpisodeConfig
+}
+
+// NewEpisodeManager creates a manager with defaults applied.
+func NewEpisodeManager(sessionID string, config EpisodeConfig) *EpisodeManager {
+	zeroConfig := config == (EpisodeConfig{})
+
+	if config.MaxEpisodeTokens <= 0 {
+		config.MaxEpisodeTokens = 2000
+	}
+	if config.MaxEpisodeMessages <= 0 {
+		config.MaxEpisodeMessages = 20
+	}
+	if config.TopicChangeThreshold <= 0 || config.TopicChangeThreshold > 1 {
+		config.TopicChangeThreshold = 0.5
+	}
+	if zeroConfig {
+		config.AutoCompactAfterClose = true
+	}
+
+	return &EpisodeManager{
+		episodes:   make(map[string]*Episode),
+		episodeSeq: make([]*Episode, 0),
+		sessionID:  sessionID,
+		config:     config,
+	}
+}
+
+// AddMessage adds a message into the active episode, rotating when needed.
+func (m *EpisodeManager) AddMessage(msg *StoreMessage) {
+	if msg == nil {
+		return
+	}
+
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	if m.activeEpisode == nil {
+		m.activeEpisode = m.newEpisodeLocked("")
+	}
+
+	if m.shouldCloseEpisodeLocked() {
+		closed := m.closeActiveEpisodeLocked()
+		parentID := ""
+		if closed != nil {
+			parentID = closed.ID
+		}
+		m.activeEpisode = m.newEpisodeLocked(parentID)
+	}
+
+	ep := m.activeEpisode
+	ep.MessageIDs = append(ep.MessageIDs, msg.ID)
+	ep.Tokens += msg.Tokens
+	if ep.StartTime.IsZero() {
+		ep.StartTime = msg.Timestamp
+	}
+	ep.EndTime = msg.Timestamp
+	if strings.TrimSpace(ep.Title) == "" {
+		ep.Title = buildEpisodeTitle(msg.Content)
+	}
+	if len(ep.Tags) == 0 {
+		ep.Tags = buildEpisodeTags(msg.Content)
+	}
+}
+
+// CloseActiveEpisode closes the current active episode.
+func (m *EpisodeManager) CloseActiveEpisode() *Episode {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return m.closeActiveEpisodeLocked()
+}
+
+// GetEpisode retrieves an episode by id.
+func (m *EpisodeManager) GetEpisode(id string) (*Episode, bool) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	ep, ok := m.episodes[id]
+	return ep, ok
+}
+
+// GetAllEpisodes returns all episodes in chronological order.
+func (m *EpisodeManager) GetAllEpisodes() []*Episode {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	out := make([]*Episode, len(m.episodeSeq))
+	copy(out, m.episodeSeq)
+	return out
+}
+
+// GetActiveEpisode returns the currently active episode.
+func (m *EpisodeManager) GetActiveEpisode() *Episode {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	return m.activeEpisode
+}
+
+// CompactEpisode compresses an episode into a summary.
+func (m *EpisodeManager) CompactEpisode(episodeID string, summary string) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	ep, ok := m.episodes[episodeID]
+	if !ok {
+		return fmt.Errorf("episode not found: %s", episodeID)
+	}
+
+	summary = strings.TrimSpace(summary)
+	if summary == "" {
+		return fmt.Errorf("summary cannot be empty")
+	}
+
+	ep.Summary = summary
+	ep.SummaryTokens = EstimateTokens(summary)
+	ep.Status = EpisodeCompacted
+	if strings.TrimSpace(ep.Title) == "" {
+		ep.Title = buildEpisodeTitle(summary)
+	}
+	if len(ep.Tags) == 0 {
+		ep.Tags = buildEpisodeTags(summary)
+	}
+
+	return nil
+}
+
+// GetEpisodesForContext returns reverse-chronological episodes within budget.
+// Active episode is always included when present.
+func (m *EpisodeManager) GetEpisodesForContext(tokenBudget int) []*Episode {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+
+	if tokenBudget < 0 {
+		tokenBudget = 0
+	}
+
+	result := make([]*Episode, 0)
+	included := make(map[string]bool)
+	remaining := tokenBudget
+
+	if m.activeEpisode != nil {
+		result = append(result, m.activeEpisode)
+		included[m.activeEpisode.ID] = true
+		remaining -= m.activeEpisode.Tokens
+		if remaining <= 0 {
+			return result
+		}
+	}
+
+	for i := len(m.episodeSeq) - 1; i >= 0; i-- {
+		ep := m.episodeSeq[i]
+		if ep == nil || included[ep.ID] {
+			continue
+		}
+
+		cost := ep.Tokens
+		if ep.Status != EpisodeActive {
+			if ep.SummaryTokens > 0 {
+				cost = ep.SummaryTokens
+			}
+		}
+
+		if cost > remaining {
+			continue
+		}
+
+		result = append(result, ep)
+		remaining -= cost
+		if remaining <= 0 {
+			break
+		}
+	}
+
+	return result
+}
+
+func (m *EpisodeManager) shouldCloseEpisodeLocked() bool {
+	if m.activeEpisode == nil {
+		return false
+	}
+	if m.config.MaxEpisodeTokens > 0 && m.activeEpisode.Tokens >= m.config.MaxEpisodeTokens {
+		return true
+	}
+	if m.config.MaxEpisodeMessages > 0 && len(m.activeEpisode.MessageIDs) >= m.config.MaxEpisodeMessages {
+		return true
+	}
+	return false
+}
+
+func (m *EpisodeManager) closeActiveEpisodeLocked() *Episode {
+	if m.activeEpisode == nil {
+		return nil
+	}
+
+	ep := m.activeEpisode
+	if ep.EndTime.IsZero() {
+		ep.EndTime = time.Now()
+	}
+	if ep.Status == EpisodeActive && m.config.AutoCompactAfterClose {
+		if strings.TrimSpace(ep.Summary) == "" {
+			ep.Summary = fmt.Sprintf("Episode %s (%d messages)", ep.ID, len(ep.MessageIDs))
+		}
+		ep.SummaryTokens = EstimateTokens(ep.Summary)
+		ep.Status = EpisodeCompacted
+	}
+
+	m.activeEpisode = nil
+	return ep
+}
+
+func (m *EpisodeManager) newEpisodeLocked(parentEpisodeID string) *Episode {
+	m.nextID++
+	ep := &Episode{
+		ID:              fmt.Sprintf("ep_%s_%d", m.sessionID, m.nextID),
+		Title:           "",
+		MessageIDs:      make([]string, 0),
+	StartTime:       time.Time{},
+	EndTime:         time.Time{},
+		Tokens:          0,
+		Summary:         "",
+		SummaryTokens:   0,
+		Status:          EpisodeActive,
+		Tags:            make([]string, 0),
+		ParentEpisodeID: parentEpisodeID,
+	}
+	m.episodes[ep.ID] = ep
+	m.episodeSeq = append(m.episodeSeq, ep)
+	return ep
+}
+
+func buildEpisodeTitle(content string) string {
+	trimmed := strings.TrimSpace(content)
+	if trimmed == "" {
+		return "Untitled Episode"
+	}
+	parts := strings.Fields(trimmed)
+	if len(parts) > 8 {
+		parts = parts[:8]
+	}
+	return strings.Join(parts, " ")
+}
+
+func buildEpisodeTags(content string) []string {
+	trimmed := strings.ToLower(strings.TrimSpace(content))
+	if trimmed == "" {
+		return nil
+	}
+	parts := strings.Fields(trimmed)
+	if len(parts) > 3 {
+		parts = parts[:3]
+	}
+	out := make([]string, 0, len(parts))
+	seen := make(map[string]bool)
+	for _, p := range parts {
+		p = strings.Trim(p, ",.;:!?()[]{}\"'")
+		if p == "" || seen[p] {
+			continue
+		}
+		seen[p] = true
+		out = append(out, p)
+	}
+	return out
+}