[Refactor]: Agent System Refactor / [Refactor]: Agent系统重构

[alexhoshina]

🎯 Purpose

As PicoClaw evolves, we're seeing growing complexity in the agent layer (pkg/agent/loop.go, now ~1200 LOC).

---

Current Pain Points

1. Monolithic structure - loop.go mixes routing, LLM iteration, tool execution, context management, summarization
2. Reactive context handling - Emergency compression when we hit limits, losing user context abruptly
3. Tool coupling - Tools have implicit dependencies on agent loop internals
4. Limited observability - Hard to debug execution flow across tool calls and LLM interactions
5. Session consistency risks - No explicit serialization, potential race conditions in multi-channel scenarios
6. Write-only memory - MEMORY.md exists but agent can't search/retrieve past information
7. Flat tool permissions - No per-agent or per-channel tool restrictions

---

Related Issues & PRs

Roadmap

• Feature: Implement AIEOS (AI Entity Object Specification) for Consistent Agent Identity #296
• Feature: Intelligent Model Routing for Cost & Performance Optimization #295
• Feature: Base Multi-agent Collaboration Framework & Shared Context #294
• Feature: Implement Model Context Protocol (MCP) support for extensible operations #290
• Introducing Swarm Mode: Multi-instance Collaboration for PicoClaw #284

Issue

• [BUG] SystemPrompt is incomplete #773

PR

[nikolasdehor]

This is a good roadmap issue. A few concrete suggestions on the refactoring priorities based on bugs I have been seeing in the issue tracker:

Highest priority: Fix sanitizeHistoryForProvider() (#704). The current implementation in context.go drops valid tool results when there are 2+ tool_calls in a single assistant message. Meanwhile, sanitize.go has a correct implementation (sanitizeToolPairs) that handles this case properly. These two functions need to be consolidated as part of this refactor -- having two competing sanitization paths is a maintenance hazard.

Context management: The reactive compression approach (compress when you hit the limit) is the root of several bugs (#683 misclassifies errors as context errors, #704 compression can orphan tool pairs, #773 users think prompts are truncated). A proactive approach where context budget is tracked incrementally (token count per message, running total) would let the agent compress ahead of the limit and avoid the emergency path entirely. This also enables the static/dynamic context split that @Zhaoyikaiii mentioned in #711.

Memory system (#538): The write-only problem is real. A structured memory module with read-before-write semantics and section-based organization would be a significant improvement. This is also a prerequisite for the multi-agent shared context in #294.

Observability: Adding structured event logging (not just debug prints) at the agent loop boundaries would help with debugging all of the above. Something like:

type AgentEvent struct {
    Type      string    // "llm_call", "tool_exec", "compression", "error"
    Timestamp time.Time
    SessionKey string
    Metadata   map[string]interface{}
}

This feeds directly into the hooks feature (#738) and makes the agent loop behavior inspectable without reading source code.

Suggested PR order: sanitize consolidation -> context budget tracking -> memory restructure -> event system -> hooks. Each builds on the previous.

[is-Xiaoen]

I've been working on the session persistence piece — PR #732 replaces the full-JSON-serialize-on-every-Save pattern with append-only JSONL + logical truncation. It directly addresses pain points #5 (session consistency — no more race between maybeSummarize goroutine and the main loop) and #6 (the Store interface has read-back methods, so memory is no longer write-only).

The PR is self-contained under pkg/memory/ and doesn't touch loop.go, so it shouldn't conflict with the tools refactor (#846) or any future agent loop restructuring. Once this roadmap issue has a clearer breakdown of sub-tasks, I'm happy to do the integration PR that wires the Store into AgentLoop.

One thing worth noting: the current SessionManager.Save() takes an RLock for the snapshot but the summarize goroutine calls TruncateHistory + Save concurrently — the JSONL store sidesteps this entirely because each AddMessage is an independent file append, no read-modify-write cycle.