Merge pull request #2564 from sky5454/looper_refactor

Looper refactor: Split the monolithic 4384-line `loop.go` into 12 focused source files as Phase 1 of the agent refactor.

docs/agent-refactor/loop-split.md

@@ -0,0 +1,86 @@
+# AgentLoop File Split
+
+## Overview
+
+The `pkg/agent/loop.go` file (originally 4384 lines) has been split into 12 focused source files. This is a pure refactoring with no behavioral changes.
+
+## Goals
+
+- Reduce cognitive load when navigating agent loop code
+- Enable parallel work by decoupling concerns
+- Maintain all existing functionality and tests
+- Keep imports minimal per file
+
+## File Map
+
+| File | Lines | Responsibility |
+|------|-------|----------------|
+| `loop.go` | ~650 | Core `AgentLoop` struct, `Run`, `Stop`, `Close`, `ReloadProviderAndConfig`, `runAgentLoop` |
+| `loop_turn.go` | ~1880 | Turn execution: `runTurn`, `abortTurn`, `selectCandidates`, `askSideQuestion`, `isolatedSideQuestionProvider`, side question model config |
+| `loop_utils.go` | ~480 | Standalone utility functions: formatters, cloners, helpers (no receiver) |
+| `loop_init.go` | ~355 | `NewAgentLoop` constructor and `registerSharedTools` |
+| `loop_message.go` | ~300 | Message handling: `processMessage`, `processSystemMessage`, routing helpers, `ProcessDirect`, `ProcessHeartbeat` |
+| `loop_command.go` | ~265 | Command processing: `handleCommand`, `applyExplicitSkillCommand`, pending skills management |
+| `loop_mcp.go` | ~235 | MCP runtime: `ensureMCPInitialized`, server discovery, deferred server handling |
+| `loop_event.go` | ~205 | Event system helpers: `emitEvent`, `logEvent`, `hookAbortError`, `newTurnEventScope`, `MountHook`, `SubscribeEvents` |
+| `loop_media.go` | ~198 | Media resolution: `resolveMediaRefs`, artifact building, MIME detection |
+| `loop_outbound.go` | ~165 | Response publishing: `PublishResponseIfNeeded`, `publishPicoReasoning`, `handleReasoning` |
+| `loop_transcribe.go` | ~110 | Audio transcription: `transcribeAudioInMessage`, `sendTranscriptionFeedback` |
+| `loop_steering.go` | ~97 | Steering queue: `runTurnWithSteering`, `processMessageSync`, `resolveSteeringTarget` |
+| `loop_inject.go` | ~104 | Setter injection: `SetChannelManager`, `SetMediaStore`, `SetTranscriber`, `GetRegistry`, `GetConfig`, `RecordLastChannel` |
+
+## Core Principles Applied
+
+### 1. Same Package, Independent Files
+All files belong to the `agent` package and compile together. This preserves the original visibility rules — no interface abstraction was introduced in this phase.
+
+### 2. No Logic Changes
+All functions were moved verbatim (except updating import statements). The extraction script used the original `loop.go.backup` as source of truth to ensure no drift.
+
+### 3. Shared Types Remain in loop.go
+The `AgentLoop` struct, `processOptions`, `continuationTarget`, and all hook/event types stay in `loop.go` since they are referenced across files.
+
+### 4. Turn State Is Central
+`loop_turn.go` is the largest file because the turn lifecycle (`runTurn`) is inherently large. It contains the core LLM interaction loop, tool execution, subturn spawning, and steering injection.
+
+## What's Left in loop.go
+
+```go
+// Core struct
+type AgentLoop struct { ... }
+
+// Main lifecycle
+func (al *AgentLoop) Run(ctx context.Context) error
+func (al *AgentLoop) Stop()
+func (al *AgentLoop) Close()
+func (al *AgentLoop) ReloadProviderAndConfig(ctx, provider, cfg)
+
+// Turn orchestration (calls into loop_turn.go)
+func (al *AgentLoop) runAgentLoop(ctx, agent, opts) (string, error)
+```
+
+## Extraction Method
+
+The split was done programmatically using Node.js to:
+1. Identify function boundaries using brace counting
+2. Extract each function to its target file
+3. Add necessary imports to each file
+4. Remove the extracted function from loop.go
+5. Run `go fmt` and `go vet` to verify
+
+## Testing
+
+All existing tests pass. The 5 failing tests (`TestGlobalSkillFileContentChange` and 4 Seahorse tests) are pre-existing failures unrelated to this refactor (database file locking issues on Windows).
+
+Build status: `go build ./pkg/agent/...` passes with no errors.
+
+## Phase 2: Dependency Inversion (Planned)
+
+A future phase will introduce interface types to decouple `AgentLoop` from its dependencies, enabling:
+- Easier testing with mock dependencies
+- Alternative runtime configurations
+- Cleaner boundaries for MCP and other extensions
+
+## See Also
+
+- [context.md](context.md) — context management and session handling

pkg/agent/loop_command.go

@@ -0,0 +1,266 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+
+package agent
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/commands"
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+func (al *AgentLoop) handleCommand(
+	ctx context.Context,
+	msg bus.InboundMessage,
+	agent *AgentInstance,
+	opts *processOptions,
+) (string, bool) {
+	normalizeProcessOptionsInPlace(opts)
+
+	if !commands.HasCommandPrefix(msg.Content) {
+		return "", false
+	}
+
+	if matched, handled, reply := al.applyExplicitSkillCommand(msg.Content, agent, opts); matched {
+		return reply, handled
+	}
+
+	if al.cmdRegistry == nil {
+		return "", false
+	}
+
+	rt := al.buildCommandsRuntime(ctx, agent, opts)
+	executor := commands.NewExecutor(al.cmdRegistry, rt)
+
+	var commandReply string
+	result := executor.Execute(ctx, commands.Request{
+		Channel:  msg.Channel,
+		ChatID:   msg.ChatID,
+		SenderID: msg.SenderID,
+		Text:     msg.Content,
+		Reply: func(text string) error {
+			commandReply = text
+			return nil
+		},
+	})
+
+	switch result.Outcome {
+	case commands.OutcomeHandled:
+		if result.Err != nil {
+			return mapCommandError(result), true
+		}
+		if commandReply != "" {
+			return commandReply, true
+		}
+		return "", true
+	default: // OutcomePassthrough — let the message fall through to LLM
+		return "", false
+	}
+}
+
+func (al *AgentLoop) applyExplicitSkillCommand(
+	raw string,
+	agent *AgentInstance,
+	opts *processOptions,
+) (matched bool, handled bool, reply string) {
+	normalizeProcessOptionsInPlace(opts)
+
+	cmdName, ok := commands.CommandName(raw)
+	if !ok || cmdName != "use" {
+		return false, false, ""
+	}
+
+	if agent == nil || agent.ContextBuilder == nil {
+		return true, true, commandsUnavailableSkillMessage()
+	}
+
+	parts := strings.Fields(strings.TrimSpace(raw))
+	if len(parts) < 2 {
+		return true, true, buildUseCommandHelp(agent)
+	}
+
+	arg := strings.TrimSpace(parts[1])
+	if strings.EqualFold(arg, "clear") || strings.EqualFold(arg, "off") {
+		if opts != nil {
+			al.clearPendingSkills(opts.Dispatch.SessionKey)
+		}
+		return true, true, "Cleared pending skill override."
+	}
+
+	skillName, ok := agent.ContextBuilder.ResolveSkillName(arg)
+	if !ok {
+		return true, true, fmt.Sprintf("Unknown skill: %s\nUse /list skills to see installed skills.", arg)
+	}
+
+	if len(parts) < 3 {
+		if opts == nil || strings.TrimSpace(opts.Dispatch.SessionKey) == "" {
+			return true, true, commandsUnavailableSkillMessage()
+		}
+		al.setPendingSkills(opts.Dispatch.SessionKey, []string{skillName})
+		return true, true, fmt.Sprintf(
+			"Skill %q is armed for your next message. Send your next prompt normally, or use /use clear to cancel.",
+			skillName,
+		)
+	}
+
+	message := strings.TrimSpace(strings.Join(parts[2:], " "))
+	if message == "" {
+		return true, true, buildUseCommandHelp(agent)
+	}
+
+	if opts != nil {
+		opts.ForcedSkills = append(opts.ForcedSkills, skillName)
+		opts.Dispatch.UserMessage = message
+		opts.UserMessage = message
+	}
+
+	return true, false, ""
+}
+
+func (al *AgentLoop) buildCommandsRuntime(
+	ctx context.Context,
+	agent *AgentInstance,
+	opts *processOptions,
+) *commands.Runtime {
+	normalizeProcessOptionsInPlace(opts)
+
+	registry := al.GetRegistry()
+	cfg := al.GetConfig()
+	rt := &commands.Runtime{
+		Config:          cfg,
+		ListAgentIDs:    registry.ListAgentIDs,
+		ListDefinitions: al.cmdRegistry.Definitions,
+		GetEnabledChannels: func() []string {
+			if al.channelManager == nil {
+				return nil
+			}
+			return al.channelManager.GetEnabledChannels()
+		},
+		GetActiveTurn: func() any {
+			info := al.GetActiveTurn()
+			if info == nil {
+				return nil
+			}
+			return info
+		},
+		SwitchChannel: func(value string) error {
+			if al.channelManager == nil {
+				return fmt.Errorf("channel manager not initialized")
+			}
+			if _, exists := al.channelManager.GetChannel(value); !exists && value != "cli" {
+				return fmt.Errorf("channel '%s' not found or not enabled", value)
+			}
+			return nil
+		},
+	}
+	if agent != nil && agent.ContextBuilder != nil {
+		rt.ListSkillNames = agent.ContextBuilder.ListSkillNames
+	}
+	rt.ReloadConfig = func() error {
+		if al.reloadFunc == nil {
+			return fmt.Errorf("reload not configured")
+		}
+		return al.reloadFunc()
+	}
+	if agent != nil {
+		if agent.ContextBuilder != nil {
+			rt.ListSkillNames = agent.ContextBuilder.ListSkillNames
+		}
+		rt.GetModelInfo = func() (string, string) {
+			return agent.Model, resolvedCandidateProvider(agent.Candidates, cfg.Agents.Defaults.Provider)
+		}
+		rt.SwitchModel = func(value string) (string, error) {
+			value = strings.TrimSpace(value)
+			modelCfg, err := resolvedModelConfig(cfg, value, agent.Workspace)
+			if err != nil {
+				return "", err
+			}
+
+			nextProvider, _, err := providers.CreateProviderFromConfig(modelCfg)
+			if err != nil {
+				return "", fmt.Errorf("failed to initialize model %q: %w", value, err)
+			}
+
+			nextCandidates := resolveModelCandidates(cfg, cfg.Agents.Defaults.Provider, value, agent.Fallbacks)
+			if len(nextCandidates) == 0 {
+				return "", fmt.Errorf("model %q did not resolve to any provider candidates", value)
+			}
+
+			oldModel := agent.Model
+			oldProvider := agent.Provider
+			agent.Model = value
+			agent.Provider = nextProvider
+			agent.Candidates = nextCandidates
+			agent.ThinkingLevel = parseThinkingLevel(modelCfg.ThinkingLevel)
+
+			if oldProvider != nil && oldProvider != nextProvider {
+				if stateful, ok := oldProvider.(providers.StatefulProvider); ok {
+					stateful.Close()
+				}
+			}
+			return oldModel, nil
+		}
+
+		rt.ClearHistory = func() error {
+			if opts == nil {
+				return fmt.Errorf("process options not available")
+			}
+			return al.contextManager.Clear(ctx, opts.SessionKey)
+		}
+
+		rt.AskSideQuestion = func(ctx context.Context, question string) (string, error) {
+			return al.askSideQuestion(ctx, agent, opts, question)
+		}
+	}
+	return rt
+}
+
+func (al *AgentLoop) setPendingSkills(sessionKey string, skillNames []string) {
+	sessionKey = strings.TrimSpace(sessionKey)
+	if sessionKey == "" || len(skillNames) == 0 {
+		return
+	}
+
+	filtered := make([]string, 0, len(skillNames))
+	for _, name := range skillNames {
+		name = strings.TrimSpace(name)
+		if name != "" {
+			filtered = append(filtered, name)
+		}
+	}
+	if len(filtered) == 0 {
+		return
+	}
+
+	al.pendingSkills.Store(sessionKey, filtered)
+}
+
+func (al *AgentLoop) takePendingSkills(sessionKey string) []string {
+	sessionKey = strings.TrimSpace(sessionKey)
+	if sessionKey == "" {
+		return nil
+	}
+
+	value, ok := al.pendingSkills.LoadAndDelete(sessionKey)
+	if !ok {
+		return nil
+	}
+
+	skills, ok := value.([]string)
+	if !ok {
+		return nil
+	}
+
+	return append([]string(nil), skills...)
+}
+
+func (al *AgentLoop) clearPendingSkills(sessionKey string) {
+	sessionKey = strings.TrimSpace(sessionKey)
+	if sessionKey == "" {
+		return
+	}
+	al.pendingSkills.Delete(sessionKey)
+}

pkg/agent/loop_event.go

@@ -0,0 +1,206 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+
+package agent
+
+import (
+	"fmt"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+func (al *AgentLoop) newTurnEventScope(agentID, sessionKey string, turnCtx *TurnContext) turnEventScope {
+	seq := al.turnSeq.Add(1)
+	return turnEventScope{
+		agentID:    agentID,
+		sessionKey: sessionKey,
+		turnID:     fmt.Sprintf("%s-turn-%d", agentID, seq),
+		context:    cloneTurnContext(turnCtx),
+	}
+}
+
+func (ts turnEventScope) meta(iteration int, source, tracePath string) EventMeta {
+	return EventMeta{
+		AgentID:     ts.agentID,
+		TurnID:      ts.turnID,
+		SessionKey:  ts.sessionKey,
+		Iteration:   iteration,
+		Source:      source,
+		TracePath:   tracePath,
+		turnContext: cloneTurnContext(ts.context),
+	}
+}
+
+func (al *AgentLoop) emitEvent(kind EventKind, meta EventMeta, payload any) {
+	clonedMeta := cloneEventMeta(meta)
+	evt := Event{
+		Kind:    kind,
+		Meta:    clonedMeta,
+		Context: cloneTurnContext(clonedMeta.turnContext),
+		Payload: payload,
+	}
+
+	if al == nil || al.eventBus == nil {
+		return
+	}
+
+	al.logEvent(evt)
+
+	al.eventBus.Emit(evt)
+}
+
+func (al *AgentLoop) hookAbortError(ts *turnState, stage string, decision HookDecision) error {
+	reason := decision.Reason
+	if reason == "" {
+		reason = "hook requested turn abort"
+	}
+
+	err := fmt.Errorf("hook aborted turn during %s: %s", stage, reason)
+	al.emitEvent(
+		EventKindError,
+		ts.eventMeta("hooks", "turn.error"),
+		ErrorPayload{
+			Stage:   "hook." + stage,
+			Message: err.Error(),
+		},
+	)
+	return err
+}
+
+func (al *AgentLoop) logEvent(evt Event) {
+	fields := map[string]any{
+		"event_kind":  evt.Kind.String(),
+		"agent_id":    evt.Meta.AgentID,
+		"turn_id":     evt.Meta.TurnID,
+		"session_key": evt.Meta.SessionKey,
+		"iteration":   evt.Meta.Iteration,
+	}
+
+	if evt.Meta.TracePath != "" {
+		fields["trace"] = evt.Meta.TracePath
+	}
+	if evt.Meta.Source != "" {
+		fields["source"] = evt.Meta.Source
+	}
+
+	appendEventContextFields(fields, evt.Context)
+
+	switch payload := evt.Payload.(type) {
+	case TurnStartPayload:
+		fields["user_len"] = len(payload.UserMessage)
+		fields["media_count"] = payload.MediaCount
+	case TurnEndPayload:
+		fields["status"] = payload.Status
+		fields["iterations_total"] = payload.Iterations
+		fields["duration_ms"] = payload.Duration.Milliseconds()
+		fields["final_len"] = payload.FinalContentLen
+	case LLMRequestPayload:
+		fields["model"] = payload.Model
+		fields["messages"] = payload.MessagesCount
+		fields["tools"] = payload.ToolsCount
+		fields["max_tokens"] = payload.MaxTokens
+	case LLMDeltaPayload:
+		fields["content_delta_len"] = payload.ContentDeltaLen
+		fields["reasoning_delta_len"] = payload.ReasoningDeltaLen
+	case LLMResponsePayload:
+		fields["content_len"] = payload.ContentLen
+		fields["tool_calls"] = payload.ToolCalls
+		fields["has_reasoning"] = payload.HasReasoning
+	case LLMRetryPayload:
+		fields["attempt"] = payload.Attempt
+		fields["max_retries"] = payload.MaxRetries
+		fields["reason"] = payload.Reason
+		fields["error"] = payload.Error
+		fields["backoff_ms"] = payload.Backoff.Milliseconds()
+	case ContextCompressPayload:
+		fields["reason"] = payload.Reason
+		fields["dropped_messages"] = payload.DroppedMessages
+		fields["remaining_messages"] = payload.RemainingMessages
+	case SessionSummarizePayload:
+		fields["summarized_messages"] = payload.SummarizedMessages
+		fields["kept_messages"] = payload.KeptMessages
+		fields["summary_len"] = payload.SummaryLen
+		fields["omitted_oversized"] = payload.OmittedOversized
+	case ToolExecStartPayload:
+		fields["tool"] = payload.Tool
+		fields["args_count"] = len(payload.Arguments)
+	case ToolExecEndPayload:
+		fields["tool"] = payload.Tool
+		fields["duration_ms"] = payload.Duration.Milliseconds()
+		fields["for_llm_len"] = payload.ForLLMLen
+		fields["for_user_len"] = payload.ForUserLen
+		fields["is_error"] = payload.IsError
+		fields["async"] = payload.Async
+	case ToolExecSkippedPayload:
+		fields["tool"] = payload.Tool
+		fields["reason"] = payload.Reason
+	case SteeringInjectedPayload:
+		fields["count"] = payload.Count
+		fields["total_content_len"] = payload.TotalContentLen
+	case FollowUpQueuedPayload:
+		fields["source_tool"] = payload.SourceTool
+		fields["content_len"] = payload.ContentLen
+	case InterruptReceivedPayload:
+		fields["interrupt_kind"] = payload.Kind
+		fields["role"] = payload.Role
+		fields["content_len"] = payload.ContentLen
+		fields["queue_depth"] = payload.QueueDepth
+		fields["hint_len"] = payload.HintLen
+	case SubTurnSpawnPayload:
+		fields["child_agent_id"] = payload.AgentID
+		fields["label"] = payload.Label
+	case SubTurnEndPayload:
+		fields["child_agent_id"] = payload.AgentID
+		fields["status"] = payload.Status
+	case SubTurnResultDeliveredPayload:
+		fields["target_channel"] = payload.TargetChannel
+		fields["target_chat_id"] = payload.TargetChatID
+		fields["content_len"] = payload.ContentLen
+	case ErrorPayload:
+		fields["stage"] = payload.Stage
+		fields["error"] = payload.Message
+	}
+
+	logger.InfoCF("eventbus", fmt.Sprintf("Agent event: %s", evt.Kind.String()), fields)
+}
+
+// MountHook registers an in-process hook on the agent loop.
+func (al *AgentLoop) MountHook(reg HookRegistration) error {
+	if al == nil || al.hooks == nil {
+		return fmt.Errorf("hook manager is not initialized")
+	}
+	return al.hooks.Mount(reg)
+}
+
+// UnmountHook removes a previously registered in-process hook.
+func (al *AgentLoop) UnmountHook(name string) {
+	if al == nil || al.hooks == nil {
+		return
+	}
+	al.hooks.Unmount(name)
+}
+
+// SubscribeEvents registers a subscriber for agent-loop events.
+func (al *AgentLoop) SubscribeEvents(buffer int) EventSubscription {
+	if al == nil || al.eventBus == nil {
+		ch := make(chan Event)
+		close(ch)
+		return EventSubscription{C: ch}
+	}
+	return al.eventBus.Subscribe(buffer)
+}
+
+// UnsubscribeEvents removes a previously registered event subscriber.
+func (al *AgentLoop) UnsubscribeEvents(id uint64) {
+	if al == nil || al.eventBus == nil {
+		return
+	}
+	al.eventBus.Unsubscribe(id)
+}
+
+// EventDrops returns the number of dropped events for the given kind.
+func (al *AgentLoop) EventDrops(kind EventKind) int64 {
+	if al == nil || al.eventBus == nil {
+		return 0
+	}
+	return al.eventBus.Dropped(kind)
+}

pkg/agent/loop_init.go

@@ -0,0 +1,353 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+
+package agent
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/audio/tts"
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/commands"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/skills"
+	"github.com/sipeed/picoclaw/pkg/state"
+	"github.com/sipeed/picoclaw/pkg/tools"
+)
+
+func NewAgentLoop(
+	cfg *config.Config,
+	msgBus *bus.MessageBus,
+	provider providers.LLMProvider,
+) *AgentLoop {
+	registry := NewAgentRegistry(cfg, provider)
+
+	// Set up shared fallback chain with rate limiting.
+	cooldown := providers.NewCooldownTracker()
+	rl := providers.NewRateLimiterRegistry()
+	// Register rate limiters for all agents' candidates so that RPM limits
+	// configured in ModelConfig are enforced before each LLM call.
+	for _, agentID := range registry.ListAgentIDs() {
+		if agent, ok := registry.GetAgent(agentID); ok {
+			rl.RegisterCandidates(agent.Candidates)
+			rl.RegisterCandidates(agent.LightCandidates)
+		}
+	}
+	fallbackChain := providers.NewFallbackChain(cooldown, rl)
+
+	// Create state manager using default agent's workspace for channel recording
+	defaultAgent := registry.GetDefaultAgent()
+	var stateManager *state.Manager
+	if defaultAgent != nil {
+		stateManager = state.NewManager(defaultAgent.Workspace)
+	}
+
+	eventBus := NewEventBus()
+
+	// Determine worker pool size from config (default: 1 = sequential)
+	workerPoolSize := cfg.Agents.Defaults.MaxParallelTurns
+	if workerPoolSize <= 0 {
+		workerPoolSize = 1
+	}
+
+	al := &AgentLoop{
+		bus:         msgBus,
+		cfg:         cfg,
+		registry:    registry,
+		state:       stateManager,
+		eventBus:    eventBus,
+		fallback:    fallbackChain,
+		cmdRegistry: commands.NewRegistry(commands.BuiltinDefinitions()),
+		steering:    newSteeringQueue(parseSteeringMode(cfg.Agents.Defaults.SteeringMode)),
+		workerSem:   make(chan struct{}, workerPoolSize),
+	}
+	al.providerFactory = providers.CreateProviderFromConfig
+	al.hooks = NewHookManager(eventBus)
+	configureHookManagerFromConfig(al.hooks, cfg)
+	al.contextManager = al.resolveContextManager()
+
+	// Register shared tools to all agents (now that al is created)
+	registerSharedTools(al, cfg, msgBus, registry, provider)
+
+	return al
+}
+
+func registerSharedTools(
+	al *AgentLoop,
+	cfg *config.Config,
+	msgBus *bus.MessageBus,
+	registry *AgentRegistry,
+	provider providers.LLMProvider,
+) {
+	allowReadPaths := buildAllowReadPatterns(cfg)
+	var ttsProvider tts.TTSProvider
+	if cfg.Tools.IsToolEnabled("send_tts") {
+		ttsProvider = tts.DetectTTS(cfg)
+		if ttsProvider == nil {
+			logger.WarnCF("voice-tts", "send_tts enabled but no TTS provider configured", nil)
+		}
+	}
+
+	for _, agentID := range registry.ListAgentIDs() {
+		agent, ok := registry.GetAgent(agentID)
+		if !ok {
+			continue
+		}
+
+		if cfg.Tools.IsToolEnabled("web") {
+			searchTool, err := tools.NewWebSearchTool(tools.WebSearchToolOptions{
+				BraveAPIKeys:          cfg.Tools.Web.Brave.APIKeys.Values(),
+				BraveMaxResults:       cfg.Tools.Web.Brave.MaxResults,
+				BraveEnabled:          cfg.Tools.Web.Brave.Enabled,
+				TavilyAPIKeys:         cfg.Tools.Web.Tavily.APIKeys.Values(),
+				TavilyBaseURL:         cfg.Tools.Web.Tavily.BaseURL,
+				TavilyMaxResults:      cfg.Tools.Web.Tavily.MaxResults,
+				TavilyEnabled:         cfg.Tools.Web.Tavily.Enabled,
+				DuckDuckGoMaxResults:  cfg.Tools.Web.DuckDuckGo.MaxResults,
+				DuckDuckGoEnabled:     cfg.Tools.Web.DuckDuckGo.Enabled,
+				PerplexityAPIKeys:     cfg.Tools.Web.Perplexity.APIKeys.Values(),
+				PerplexityMaxResults:  cfg.Tools.Web.Perplexity.MaxResults,
+				PerplexityEnabled:     cfg.Tools.Web.Perplexity.Enabled,
+				SearXNGBaseURL:        cfg.Tools.Web.SearXNG.BaseURL,
+				SearXNGMaxResults:     cfg.Tools.Web.SearXNG.MaxResults,
+				SearXNGEnabled:        cfg.Tools.Web.SearXNG.Enabled,
+				GLMSearchAPIKey:       cfg.Tools.Web.GLMSearch.APIKey.String(),
+				GLMSearchBaseURL:      cfg.Tools.Web.GLMSearch.BaseURL,
+				GLMSearchEngine:       cfg.Tools.Web.GLMSearch.SearchEngine,
+				GLMSearchMaxResults:   cfg.Tools.Web.GLMSearch.MaxResults,
+				GLMSearchEnabled:      cfg.Tools.Web.GLMSearch.Enabled,
+				BaiduSearchAPIKey:     cfg.Tools.Web.BaiduSearch.APIKey.String(),
+				BaiduSearchBaseURL:    cfg.Tools.Web.BaiduSearch.BaseURL,
+				BaiduSearchMaxResults: cfg.Tools.Web.BaiduSearch.MaxResults,
+				BaiduSearchEnabled:    cfg.Tools.Web.BaiduSearch.Enabled,
+				Proxy:                 cfg.Tools.Web.Proxy,
+			})
+			if err != nil {
+				logger.ErrorCF("agent", "Failed to create web search tool", map[string]any{"error": err.Error()})
+			} else if searchTool != nil {
+				agent.Tools.Register(searchTool)
+			}
+		}
+		if cfg.Tools.IsToolEnabled("web_fetch") {
+			fetchTool, err := tools.NewWebFetchToolWithProxy(
+				50000,
+				cfg.Tools.Web.Proxy,
+				cfg.Tools.Web.Format,
+				cfg.Tools.Web.FetchLimitBytes,
+				cfg.Tools.Web.PrivateHostWhitelist)
+			if err != nil {
+				logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
+			} else {
+				agent.Tools.Register(fetchTool)
+			}
+		}
+
+		// Hardware tools (I2C, SPI) - Linux only, returns error on other platforms
+		if cfg.Tools.IsToolEnabled("i2c") {
+			agent.Tools.Register(tools.NewI2CTool())
+		}
+		if cfg.Tools.IsToolEnabled("spi") {
+			agent.Tools.Register(tools.NewSPITool())
+		}
+
+		// Message tool
+		if cfg.Tools.IsToolEnabled("message") {
+			messageTool := tools.NewMessageTool()
+			messageTool.SetSendCallback(func(
+				ctx context.Context,
+				channel, chatID, content, replyToMessageID string,
+			) error {
+				pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
+				defer pubCancel()
+				outboundCtx := bus.NewOutboundContext(channel, chatID, replyToMessageID)
+				outboundAgentID, outboundSessionKey, outboundScope := outboundTurnMetadata(
+					tools.ToolAgentID(ctx),
+					tools.ToolSessionKey(ctx),
+					tools.ToolSessionScope(ctx),
+				)
+				return msgBus.PublishOutbound(pubCtx, bus.OutboundMessage{
+					Context:          outboundCtx,
+					AgentID:          outboundAgentID,
+					SessionKey:       outboundSessionKey,
+					Scope:            outboundScope,
+					Content:          content,
+					ReplyToMessageID: replyToMessageID,
+				})
+			})
+			agent.Tools.Register(messageTool)
+		}
+		if cfg.Tools.IsToolEnabled("reaction") {
+			reactionTool := tools.NewReactionTool()
+			reactionTool.SetReactionCallback(func(ctx context.Context, channel, chatID, messageID string) error {
+				if al.channelManager == nil {
+					return fmt.Errorf("channel manager not configured")
+				}
+				ch, ok := al.channelManager.GetChannel(channel)
+				if !ok {
+					return fmt.Errorf("channel %s not found", channel)
+				}
+				rc, ok := ch.(channels.ReactionCapable)
+				if !ok {
+					return fmt.Errorf("channel %s does not support reactions", channel)
+				}
+				_, err := rc.ReactToMessage(ctx, chatID, messageID)
+				return err
+			})
+			agent.Tools.Register(reactionTool)
+		}
+
+		// Send file tool (outbound media via MediaStore — store injected later by SetMediaStore)
+		if cfg.Tools.IsToolEnabled("send_file") {
+			sendFileTool := tools.NewSendFileTool(
+				agent.Workspace,
+				cfg.Agents.Defaults.RestrictToWorkspace,
+				cfg.Agents.Defaults.GetMaxMediaSize(),
+				nil,
+				allowReadPaths,
+			)
+			agent.Tools.Register(sendFileTool)
+		}
+
+		if ttsProvider != nil {
+			agent.Tools.Register(tools.NewSendTTSTool(ttsProvider, nil))
+		}
+
+		if cfg.Tools.IsToolEnabled("load_image") {
+			loadImageTool := tools.NewLoadImageTool(
+				agent.Workspace,
+				cfg.Agents.Defaults.RestrictToWorkspace,
+				cfg.Agents.Defaults.GetMaxMediaSize(),
+				nil,
+				allowReadPaths,
+			)
+			agent.Tools.Register(loadImageTool)
+		}
+
+		// Skill discovery and installation tools
+		skills_enabled := cfg.Tools.IsToolEnabled("skills")
+		find_skills_enable := cfg.Tools.IsToolEnabled("find_skills")
+		install_skills_enable := cfg.Tools.IsToolEnabled("install_skill")
+		if skills_enabled && (find_skills_enable || install_skills_enable) {
+			registryMgr := skills.NewRegistryManagerFromToolsConfig(cfg.Tools.Skills)
+
+			if find_skills_enable {
+				searchCache := skills.NewSearchCache(
+					cfg.Tools.Skills.SearchCache.MaxSize,
+					time.Duration(cfg.Tools.Skills.SearchCache.TTLSeconds)*time.Second,
+				)
+				agent.Tools.Register(tools.NewFindSkillsTool(registryMgr, searchCache))
+			}
+
+			if install_skills_enable {
+				agent.Tools.Register(tools.NewInstallSkillTool(registryMgr, agent.Workspace))
+			}
+		}
+
+		// Spawn and spawn_status tools share a SubagentManager.
+		// Construct it when either tool is enabled (both require subagent).
+		spawnEnabled := cfg.Tools.IsToolEnabled("spawn")
+		spawnStatusEnabled := cfg.Tools.IsToolEnabled("spawn_status")
+		if (spawnEnabled || spawnStatusEnabled) && cfg.Tools.IsToolEnabled("subagent") {
+			subagentManager := tools.NewSubagentManager(provider, agent.Model, agent.Workspace)
+			subagentManager.SetLLMOptions(agent.MaxTokens, agent.Temperature)
+
+			// Inject a media resolver so the legacy RunToolLoop fallback path can
+			// resolve media:// refs in the same way the main AgentLoop does.
+			// This keeps subagent vision support working even when the optimized
+			// sub-turn spawner path is unavailable.
+			subagentManager.SetMediaResolver(func(msgs []providers.Message) []providers.Message {
+				return resolveMediaRefs(msgs, al.mediaStore, cfg.Agents.Defaults.GetMaxMediaSize())
+			})
+
+			// Set the spawner that links into AgentLoop's turnState
+			subagentManager.SetSpawner(func(
+				ctx context.Context,
+				task, label, targetAgentID string,
+				tls *tools.ToolRegistry,
+				maxTokens int,
+				temperature float64,
+				hasMaxTokens, hasTemperature bool,
+			) (*tools.ToolResult, error) {
+				// 1. Recover parent Turn State from Context
+				parentTS := turnStateFromContext(ctx)
+				if parentTS == nil {
+					// Fallback: If no turnState exists in context, create an isolated ad-hoc root turn state
+					// so that the tool can still function outside of an agent loop (e.g. tests, raw invocations).
+					parentTS = &turnState{
+						ctx:            ctx,
+						turnID:         "adhoc-root",
+						depth:          0,
+						session:        nil, // Ephemeral session not needed for adhoc spawn
+						pendingResults: make(chan *tools.ToolResult, 16),
+						concurrencySem: make(chan struct{}, 5),
+					}
+				}
+
+				// 2. Build Tools slice from registry
+				var tlSlice []tools.Tool
+				for _, name := range tls.List() {
+					if t, ok := tls.Get(name); ok {
+						tlSlice = append(tlSlice, t)
+					}
+				}
+
+				// 3. System Prompt
+				systemPrompt := "You are a subagent. Complete the given task independently and report the result.\n" +
+					"You have access to tools - use them as needed to complete your task.\n" +
+					"After completing the task, provide a clear summary of what was done.\n\n" +
+					"Task: " + task
+
+				// 4. Resolve Model
+				modelToUse := agent.Model
+				if targetAgentID != "" {
+					if targetAgent, ok := al.GetRegistry().GetAgent(targetAgentID); ok {
+						modelToUse = targetAgent.Model
+					}
+				}
+
+				// 5. Build SubTurnConfig
+				cfg := SubTurnConfig{
+					Model:        modelToUse,
+					Tools:        tlSlice,
+					SystemPrompt: systemPrompt,
+				}
+				if hasMaxTokens {
+					cfg.MaxTokens = maxTokens
+				}
+
+				// 6. Spawn SubTurn
+				return spawnSubTurn(ctx, al, parentTS, cfg)
+			})
+
+			// Clone the parent's tool registry so subagents can use all
+			// tools registered so far (file, web, etc.) but NOT spawn/
+			// spawn_status which are added below — preventing recursive
+			// subagent spawning.
+			subagentManager.SetTools(agent.Tools.Clone())
+			if spawnEnabled {
+				spawnTool := tools.NewSpawnTool(subagentManager)
+				spawnTool.SetSpawner(NewSubTurnSpawner(al))
+				currentAgentID := agentID
+				spawnTool.SetAllowlistChecker(func(targetAgentID string) bool {
+					return registry.CanSpawnSubagent(currentAgentID, targetAgentID)
+				})
+
+				agent.Tools.Register(spawnTool)
+
+				// Also register the synchronous subagent tool
+				subagentTool := tools.NewSubagentTool(subagentManager)
+				subagentTool.SetSpawner(NewSubTurnSpawner(al))
+				agent.Tools.Register(subagentTool)
+			}
+			if spawnStatusEnabled {
+				agent.Tools.Register(tools.NewSpawnStatusTool(subagentManager))
+			}
+		} else if (spawnEnabled || spawnStatusEnabled) && !cfg.Tools.IsToolEnabled("subagent") {
+			logger.WarnCF("agent", "spawn/spawn_status tools require subagent to be enabled", nil)
+		}
+	}
+}

pkg/agent/loop_inject.go

@@ -0,0 +1,103 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+
+package agent
+
+import (
+	"github.com/sipeed/picoclaw/pkg/audio/asr"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/media"
+	"github.com/sipeed/picoclaw/pkg/tools"
+)
+
+func (al *AgentLoop) RegisterTool(tool tools.Tool) {
+	registry := al.GetRegistry()
+	for _, agentID := range registry.ListAgentIDs() {
+		if agent, ok := registry.GetAgent(agentID); ok {
+			agent.Tools.Register(tool)
+		}
+	}
+}
+
+func (al *AgentLoop) SetChannelManager(cm *channels.Manager) {
+	al.channelManager = cm
+}
+
+func (al *AgentLoop) GetRegistry() *AgentRegistry {
+	al.mu.RLock()
+	defer al.mu.RUnlock()
+	return al.registry
+}
+
+func (al *AgentLoop) GetConfig() *config.Config {
+	al.mu.RLock()
+	defer al.mu.RUnlock()
+	return al.cfg
+}
+
+func (al *AgentLoop) SetMediaStore(s media.MediaStore) {
+	al.mediaStore = s
+
+	// Propagate store to all registered tools that can emit media.
+	registry := al.GetRegistry()
+	for _, agentID := range registry.ListAgentIDs() {
+		if agent, ok := registry.GetAgent(agentID); ok {
+			agent.Tools.SetMediaStore(s)
+		}
+	}
+	registry.ForEachTool("send_tts", func(t tools.Tool) {
+		if st, ok := t.(*tools.SendTTSTool); ok {
+			st.SetMediaStore(s)
+		}
+	})
+}
+
+func (al *AgentLoop) SetTranscriber(t asr.Transcriber) {
+	al.transcriber = t
+}
+
+func (al *AgentLoop) SetReloadFunc(fn func() error) {
+	al.reloadFunc = fn
+}
+
+func (al *AgentLoop) RecordLastChannel(channel string) error {
+	if al.state == nil {
+		return nil
+	}
+	return al.state.SetLastChannel(channel)
+}
+
+func (al *AgentLoop) RecordLastChatID(chatID string) error {
+	if al.state == nil {
+		return nil
+	}
+	return al.state.SetLastChatID(chatID)
+}
+
+func (al *AgentLoop) GetStartupInfo() map[string]any {
+	info := make(map[string]any)
+
+	registry := al.GetRegistry()
+	agent := registry.GetDefaultAgent()
+	if agent == nil {
+		return info
+	}
+
+	// Tools info
+	toolsList := agent.Tools.List()
+	info["tools"] = map[string]any{
+		"count": len(toolsList),
+		"names": toolsList,
+	}
+
+	// Skills info
+	info["skills"] = agent.ContextBuilder.GetSkillsInfo()
+
+	// Agents info
+	info["agents"] = map[string]any{
+		"count": len(registry.ListAgentIDs()),
+		"ids":   registry.ListAgentIDs(),
+	}
+
+	return info
+}

pkg/agent/loop_message.go

@@ -0,0 +1,302 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+
+package agent
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/constants"
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/routing"
+	"github.com/sipeed/picoclaw/pkg/session"
+	"github.com/sipeed/picoclaw/pkg/utils"
+)
+
+func (al *AgentLoop) buildContinuationTarget(msg bus.InboundMessage) (*continuationTarget, error) {
+	if msg.Channel == "system" {
+		return nil, nil
+	}
+
+	route, _, err := al.resolveMessageRoute(msg)
+	if err != nil {
+		return nil, err
+	}
+	allocation := al.allocateRouteSession(route, msg)
+
+	return &continuationTarget{
+		SessionKey: resolveScopeKey(allocation.SessionKey, msg.SessionKey),
+		Channel:    msg.Channel,
+		ChatID:     msg.ChatID,
+	}, nil
+}
+
+func (al *AgentLoop) ProcessDirect(
+	ctx context.Context,
+	content, sessionKey string,
+) (string, error) {
+	return al.ProcessDirectWithChannel(ctx, content, sessionKey, "cli", "direct")
+}
+
+func (al *AgentLoop) ProcessDirectWithChannel(
+	ctx context.Context,
+	content, sessionKey, channel, chatID string,
+) (string, error) {
+	if err := al.ensureHooksInitialized(ctx); err != nil {
+		return "", err
+	}
+	if err := al.ensureMCPInitialized(ctx); err != nil {
+		return "", err
+	}
+
+	msg := bus.InboundMessage{
+		Context: bus.InboundContext{
+			Channel:  channel,
+			ChatID:   chatID,
+			ChatType: "direct",
+			SenderID: "cron",
+		},
+		Content:    content,
+		SessionKey: sessionKey,
+	}
+
+	return al.processMessage(ctx, msg)
+}
+
+func (al *AgentLoop) ProcessHeartbeat(
+	ctx context.Context,
+	content, channel, chatID string,
+) (string, error) {
+	if err := al.ensureHooksInitialized(ctx); err != nil {
+		return "", err
+	}
+	if err := al.ensureMCPInitialized(ctx); err != nil {
+		return "", err
+	}
+
+	agent := al.GetRegistry().GetDefaultAgent()
+	if agent == nil {
+		return "", fmt.Errorf("no default agent for heartbeat")
+	}
+	dispatch := DispatchRequest{
+		SessionKey:  "heartbeat",
+		UserMessage: content,
+	}
+	if channel != "" || chatID != "" {
+		dispatch.InboundContext = &bus.InboundContext{
+			Channel:  channel,
+			ChatID:   chatID,
+			ChatType: "direct",
+			SenderID: "heartbeat",
+		}
+	}
+	return al.runAgentLoop(ctx, agent, processOptions{
+		Dispatch:             dispatch,
+		DefaultResponse:      defaultResponse,
+		EnableSummary:        false,
+		SendResponse:         false,
+		SuppressToolFeedback: true,
+		NoHistory:            true, // Don't load session history for heartbeat
+	})
+}
+
+func (al *AgentLoop) processMessage(ctx context.Context, msg bus.InboundMessage) (string, error) {
+	msg = bus.NormalizeInboundMessage(msg)
+
+	// Add message preview to log (show full content for error messages)
+	var logContent string
+	if strings.Contains(msg.Content, "Error:") || strings.Contains(msg.Content, "error") {
+		logContent = msg.Content // Full content for errors
+	} else {
+		logContent = utils.Truncate(msg.Content, 80)
+	}
+	logger.InfoCF(
+		"agent",
+		fmt.Sprintf("Processing message from %s:%s: %s", msg.Channel, msg.SenderID, logContent),
+		map[string]any{
+			"channel":     msg.Channel,
+			"chat_id":     msg.ChatID,
+			"sender_id":   msg.SenderID,
+			"session_key": msg.SessionKey,
+		},
+	)
+
+	var hadAudio bool
+	msg, hadAudio = al.transcribeAudioInMessage(ctx, msg)
+
+	// For audio messages the placeholder was deferred by the channel.
+	// Now that transcription (and optional feedback) is done, send it.
+	if hadAudio && al.channelManager != nil {
+		al.channelManager.SendPlaceholder(ctx, msg.Channel, msg.ChatID)
+	}
+
+	// Route system messages to processSystemMessage
+	if msg.Channel == "system" {
+		return al.processSystemMessage(ctx, msg)
+	}
+
+	route, agent, routeErr := al.resolveMessageRoute(msg)
+	if routeErr != nil {
+		return "", routeErr
+	}
+
+	allocation := al.allocateRouteSession(route, msg)
+
+	// Resolve session key from the route allocation, while preserving explicit
+	// agent-scoped keys supplied by the caller.
+	scopeKey := resolveScopeKey(allocation.SessionKey, msg.SessionKey)
+	sessionKey := scopeKey
+
+	// Reset message-tool state for this round so we don't skip publishing due to a previous round.
+	if tool, ok := agent.Tools.Get("message"); ok {
+		if resetter, ok := tool.(interface{ ResetSentInRound(sessionKey string) }); ok {
+			resetter.ResetSentInRound(sessionKey)
+		}
+	}
+
+	logger.InfoCF("agent", "Routed message",
+		map[string]any{
+			"agent_id":           agent.ID,
+			"scope_key":          scopeKey,
+			"session_key":        sessionKey,
+			"matched_by":         route.MatchedBy,
+			"route_agent":        route.AgentID,
+			"route_channel":      route.Channel,
+			"route_main_session": allocation.MainSessionKey,
+		})
+
+	opts := processOptions{
+		Dispatch: DispatchRequest{
+			SessionKey:     sessionKey,
+			SessionAliases: buildSessionAliases(sessionKey, append(allocation.SessionAliases, msg.SessionKey)...),
+			InboundContext: cloneInboundContext(&msg.Context),
+			RouteResult:    cloneResolvedRoute(&route),
+			SessionScope:   session.CloneScope(&allocation.Scope),
+			UserMessage:    msg.Content,
+			Media:          append([]string(nil), msg.Media...),
+		},
+		SenderID:                msg.SenderID,
+		SenderDisplayName:       msg.Sender.DisplayName,
+		DefaultResponse:         defaultResponse,
+		EnableSummary:           true,
+		SendResponse:            false,
+		AllowInterimPicoPublish: true,
+	}
+
+	// context-dependent commands check their own Runtime fields and report
+	// "unavailable" when the required capability is nil.
+	if response, handled := al.handleCommand(ctx, msg, agent, &opts); handled {
+		return response, nil
+	}
+
+	if pending := al.takePendingSkills(opts.Dispatch.SessionKey); len(pending) > 0 {
+		opts.ForcedSkills = append(opts.ForcedSkills, pending...)
+		logger.InfoCF("agent", "Applying pending skill override",
+			map[string]any{
+				"session_key": opts.Dispatch.SessionKey,
+				"skills":      strings.Join(pending, ","),
+			})
+	}
+
+	return al.runAgentLoop(ctx, agent, opts)
+}
+
+func (al *AgentLoop) resolveMessageRoute(msg bus.InboundMessage) (routing.ResolvedRoute, *AgentInstance, error) {
+	registry := al.GetRegistry()
+	inboundCtx := normalizedInboundContext(msg)
+	route := registry.ResolveRoute(inboundCtx)
+
+	agent, ok := registry.GetAgent(route.AgentID)
+	if !ok {
+		agent = registry.GetDefaultAgent()
+	}
+	if agent == nil {
+		return routing.ResolvedRoute{}, nil, fmt.Errorf("no agent available for route (agent_id=%s)", route.AgentID)
+	}
+
+	return route, agent, nil
+}
+
+func (al *AgentLoop) allocateRouteSession(route routing.ResolvedRoute, msg bus.InboundMessage) session.Allocation {
+	return session.AllocateRouteSession(session.AllocationInput{
+		AgentID:       route.AgentID,
+		Context:       normalizedInboundContext(msg),
+		SessionPolicy: route.SessionPolicy,
+	})
+}
+
+func (al *AgentLoop) processSystemMessage(
+	ctx context.Context,
+	msg bus.InboundMessage,
+) (string, error) {
+	if msg.Channel != "system" {
+		return "", fmt.Errorf(
+			"processSystemMessage called with non-system message channel: %s",
+			msg.Channel,
+		)
+	}
+
+	logger.InfoCF("agent", "Processing system message",
+		map[string]any{
+			"sender_id": msg.SenderID,
+			"chat_id":   msg.ChatID,
+		})
+
+	// Parse origin channel from chat_id (format: "channel:chat_id")
+	var originChannel, originChatID string
+	if idx := strings.Index(msg.ChatID, ":"); idx > 0 {
+		originChannel = msg.ChatID[:idx]
+		originChatID = msg.ChatID[idx+1:]
+	} else {
+		originChannel = "cli"
+		originChatID = msg.ChatID
+	}
+
+	// Extract subagent result from message content
+	// Format: "Task 'label' completed.\n\nResult:\n<actual content>"
+	content := msg.Content
+	if idx := strings.Index(content, "Result:\n"); idx >= 0 {
+		content = content[idx+8:] // Extract just the result part
+	}
+
+	// Skip internal channels - only log, don't send to user
+	if constants.IsInternalChannel(originChannel) {
+		logger.InfoCF("agent", "Subagent completed (internal channel)",
+			map[string]any{
+				"sender_id":   msg.SenderID,
+				"content_len": len(content),
+				"channel":     originChannel,
+			})
+		return "", nil
+	}
+
+	// Use default agent for system messages
+	agent := al.GetRegistry().GetDefaultAgent()
+	if agent == nil {
+		return "", fmt.Errorf("no default agent for system message")
+	}
+
+	// Use the origin session for context
+	sessionKey := session.BuildMainSessionKey(agent.ID)
+	dispatch := DispatchRequest{
+		SessionKey:  sessionKey,
+		UserMessage: fmt.Sprintf("[System: %s] %s", msg.SenderID, msg.Content),
+	}
+	if originChannel != "" || originChatID != "" {
+		dispatch.InboundContext = &bus.InboundContext{
+			Channel:  originChannel,
+			ChatID:   originChatID,
+			ChatType: "direct",
+			SenderID: msg.SenderID,
+		}
+	}
+
+	return al.runAgentLoop(ctx, agent, processOptions{
+		Dispatch:        dispatch,
+		DefaultResponse: "Background task completed.",
+		EnableSummary:   false,
+		SendResponse:    true,
+	})
+}

pkg/agent/loop_outbound.go

@@ -0,0 +1,165 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+
+package agent
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/tools"
+)
+
+func (al *AgentLoop) maybePublishError(ctx context.Context, channel, chatID, sessionKey string, err error) bool {
+	if errors.Is(err, context.Canceled) {
+		return false
+	}
+	al.PublishResponseIfNeeded(ctx, channel, chatID, sessionKey, fmt.Sprintf("Error processing message: %v", err))
+	return true
+}
+
+func (al *AgentLoop) publishResponseOrError(
+	ctx context.Context,
+	channel, chatID, sessionKey string,
+	response string,
+	err error,
+) {
+	if err != nil {
+		if !al.maybePublishError(ctx, channel, chatID, sessionKey, err) {
+			return
+		}
+		response = ""
+	}
+	al.PublishResponseIfNeeded(ctx, channel, chatID, sessionKey, response)
+}
+
+func (al *AgentLoop) PublishResponseIfNeeded(ctx context.Context, channel, chatID, sessionKey, response string) {
+	if response == "" {
+		return
+	}
+
+	alreadySentToSameChat := false
+	defaultAgent := al.GetRegistry().GetDefaultAgent()
+	if defaultAgent != nil {
+		if tool, ok := defaultAgent.Tools.Get("message"); ok {
+			if mt, ok := tool.(*tools.MessageTool); ok {
+				alreadySentToSameChat = mt.HasSentTo(sessionKey, channel, chatID)
+			}
+		}
+	}
+
+	if alreadySentToSameChat {
+		logger.DebugCF(
+			"agent",
+			"Skipped outbound (message tool already sent to same chat)",
+			map[string]any{"channel": channel, "chat_id": chatID},
+		)
+		return
+	}
+
+	al.bus.PublishOutbound(ctx, bus.OutboundMessage{
+		Context: bus.NewOutboundContext(channel, chatID, ""),
+		Content: response,
+	})
+	logger.InfoCF("agent", "Published outbound response",
+		map[string]any{
+			"channel":     channel,
+			"chat_id":     chatID,
+			"content_len": len(response),
+		})
+}
+
+func (al *AgentLoop) targetReasoningChannelID(channelName string) (chatID string) {
+	if al.channelManager == nil {
+		return ""
+	}
+	if ch, ok := al.channelManager.GetChannel(channelName); ok {
+		return ch.ReasoningChannelID()
+	}
+	return ""
+}
+
+func (al *AgentLoop) publishPicoReasoning(ctx context.Context, reasoningContent, chatID string) {
+	if reasoningContent == "" || chatID == "" {
+		return
+	}
+
+	if ctx.Err() != nil {
+		return
+	}
+
+	pubCtx, pubCancel := context.WithTimeout(ctx, 5*time.Second)
+	defer pubCancel()
+
+	if err := al.bus.PublishOutbound(pubCtx, bus.OutboundMessage{
+		Context: bus.InboundContext{
+			Channel: "pico",
+			ChatID:  chatID,
+			Raw: map[string]string{
+				metadataKeyMessageKind: messageKindThought,
+			},
+		},
+		Content: reasoningContent,
+	}); err != nil {
+		if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) ||
+			errors.Is(err, bus.ErrBusClosed) {
+			logger.DebugCF("agent", "Pico reasoning publish skipped (timeout/cancel)", map[string]any{
+				"channel": "pico",
+				"error":   err.Error(),
+			})
+		} else {
+			logger.WarnCF("agent", "Failed to publish pico reasoning (best-effort)", map[string]any{
+				"channel": "pico",
+				"error":   err.Error(),
+			})
+		}
+	}
+}
+
+func (al *AgentLoop) handleReasoning(
+	ctx context.Context,
+	reasoningContent, channelName, channelID string,
+) {
+	if reasoningContent == "" || channelName == "" || channelID == "" {
+		return
+	}
+
+	// Check context cancellation before attempting to publish,
+	// since PublishOutbound's select may race between send and ctx.Done().
+	if ctx.Err() != nil {
+		return
+	}
+
+	// Use a short timeout so the goroutine does not block indefinitely when
+	// the outbound bus is full.  Reasoning output is best-effort; dropping it
+	// is acceptable to avoid goroutine accumulation.
+	pubCtx, pubCancel := context.WithTimeout(ctx, 5*time.Second)
+	defer pubCancel()
+
+	if err := al.bus.PublishOutbound(pubCtx, bus.OutboundMessage{
+		Context: bus.NewOutboundContext(channelName, channelID, ""),
+		Content: reasoningContent,
+	}); err != nil {
+		// Treat context.DeadlineExceeded / context.Canceled as expected
+		// (bus full under load, or parent canceled).  Check the error
+		// itself rather than ctx.Err(), because pubCtx may time out
+		// (5 s) while the parent ctx is still active.
+		// Also treat ErrBusClosed as expected — it occurs during normal
+		// shutdown when the bus is closed before all goroutines finish.
+		if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) ||
+			errors.Is(err, bus.ErrBusClosed) {
+			logger.DebugCF("agent", "Reasoning publish skipped (timeout/cancel)", map[string]any{
+				"channel": channelName,
+				"error":   err.Error(),
+			})
+		} else {
+			logger.WarnCF("agent", "Failed to publish reasoning (best-effort)", map[string]any{
+				"channel": channelName,
+				"error":   err.Error(),
+			})
+		}
+	}
+}

pkg/agent/loop_steering.go

@@ -0,0 +1,96 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+
+package agent
+
+import (
+	"context"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+func (al *AgentLoop) processMessageSync(ctx context.Context, msg bus.InboundMessage) {
+	if al.channelManager != nil {
+		defer al.channelManager.InvokeTypingStop(msg.Channel, msg.ChatID)
+	}
+
+	response, err := al.processMessage(ctx, msg)
+	al.publishResponseOrError(ctx, msg.Channel, msg.ChatID, msg.SessionKey, response, err)
+}
+
+func (al *AgentLoop) runTurnWithSteering(ctx context.Context, initialMsg bus.InboundMessage) {
+	// Process the initial message
+	response, err := al.processMessage(ctx, initialMsg)
+	if err != nil {
+		if !al.maybePublishError(ctx, initialMsg.Channel, initialMsg.ChatID, initialMsg.SessionKey, err) {
+			return // context canceled
+		}
+		response = ""
+	}
+	finalResponse := response
+
+	// Build continuation target
+	target, targetErr := al.buildContinuationTarget(initialMsg)
+	if targetErr != nil {
+		logger.WarnCF("agent", "Failed to build steering continuation target",
+			map[string]any{
+				"channel": initialMsg.Channel,
+				"error":   targetErr.Error(),
+			})
+		return
+	}
+	if target == nil {
+		// System message or non-routable, response already published
+		return
+	}
+
+	// Drain steering queue using existing Continue mechanism
+	for al.pendingSteeringCountForScope(target.SessionKey) > 0 {
+		// Check for context cancellation between iterations
+		if ctx.Err() != nil {
+			return
+		}
+
+		logger.InfoCF("agent", "Continuing queued steering after turn end",
+			map[string]any{
+				"channel":     target.Channel,
+				"chat_id":     target.ChatID,
+				"session_key": target.SessionKey,
+				"queue_depth": al.pendingSteeringCountForScope(target.SessionKey),
+			})
+
+		continued, continueErr := al.Continue(ctx, target.SessionKey, target.Channel, target.ChatID)
+		if continueErr != nil {
+			logger.WarnCF("agent", "Failed to continue queued steering",
+				map[string]any{
+					"channel": target.Channel,
+					"chat_id": target.ChatID,
+					"error":   continueErr.Error(),
+				})
+			break
+		}
+		if continued == "" {
+			break
+		}
+		finalResponse = continued
+	}
+
+	// Publish final response
+	if finalResponse != "" {
+		al.PublishResponseIfNeeded(ctx, target.Channel, target.ChatID, target.SessionKey, finalResponse)
+	}
+}
+
+func (al *AgentLoop) resolveSteeringTarget(msg bus.InboundMessage) (string, string, bool) {
+	if msg.Channel == "system" {
+		return "", "", false
+	}
+
+	route, agent, err := al.resolveMessageRoute(msg)
+	if err != nil || agent == nil {
+		return "", "", false
+	}
+	allocation := al.allocateRouteSession(route, msg)
+
+	return resolveScopeKey(allocation.SessionKey, msg.SessionKey), agent.ID, true
+}

pkg/agent/loop_transcribe.go

@@ -0,0 +1,109 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+
+package agent
+
+import (
+	"context"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/utils"
+)
+
+func (al *AgentLoop) transcribeAudioInMessage(ctx context.Context, msg bus.InboundMessage) (bus.InboundMessage, bool) {
+	if al.transcriber == nil || al.mediaStore == nil || len(msg.Media) == 0 {
+		return msg, false
+	}
+
+	// Transcribe each audio media ref in order.
+	var transcriptions []string
+	var keptMedia []string
+	for _, ref := range msg.Media {
+		path, meta, err := al.mediaStore.ResolveWithMeta(ref)
+		if err != nil {
+			logger.WarnCF("voice", "Failed to resolve media ref", map[string]any{"ref": ref, "error": err})
+			keptMedia = append(keptMedia, ref)
+			continue
+		}
+		if !utils.IsAudioFile(meta.Filename, meta.ContentType) {
+			keptMedia = append(keptMedia, ref)
+			continue
+		}
+		result, err := al.transcriber.Transcribe(ctx, path)
+		if err != nil {
+			logger.WarnCF("voice", "Transcription failed", map[string]any{"ref": ref, "error": err})
+			transcriptions = append(transcriptions, "")
+			keptMedia = append(keptMedia, ref)
+			continue
+		}
+		transcriptions = append(transcriptions, result.Text)
+	}
+
+	if len(transcriptions) == 0 {
+		return msg, false
+	}
+
+	al.sendTranscriptionFeedback(ctx, msg.Channel, msg.ChatID, msg.MessageID, transcriptions)
+
+	// Replace audio annotations sequentially with transcriptions.
+	idx := 0
+	newContent := audioAnnotationRe.ReplaceAllStringFunc(msg.Content, func(match string) string {
+		if idx >= len(transcriptions) {
+			return match
+		}
+		text := transcriptions[idx]
+		idx++
+		if text == "" {
+			return match
+		}
+		return "[voice: " + text + "]"
+	})
+
+	// Append any remaining transcriptions not matched by an annotation.
+	for ; idx < len(transcriptions); idx++ {
+		if transcriptions[idx] != "" {
+			newContent += "\n[voice: " + transcriptions[idx] + "]"
+		}
+	}
+
+	msg.Content = newContent
+	msg.Media = keptMedia
+	return msg, true
+}
+
+func (al *AgentLoop) sendTranscriptionFeedback(
+	ctx context.Context,
+	channel, chatID, messageID string,
+	validTexts []string,
+) {
+	if !al.cfg.Voice.EchoTranscription {
+		return
+	}
+	if al.channelManager == nil {
+		return
+	}
+
+	var nonEmpty []string
+	for _, t := range validTexts {
+		if t != "" {
+			nonEmpty = append(nonEmpty, t)
+		}
+	}
+
+	var feedbackMsg string
+	if len(nonEmpty) > 0 {
+		feedbackMsg = "Transcript: " + strings.Join(nonEmpty, "\n")
+	} else {
+		feedbackMsg = "No voice detected in the audio"
+	}
+
+	err := al.channelManager.SendMessage(ctx, bus.OutboundMessage{
+		Context:          bus.NewOutboundContext(channel, chatID, messageID),
+		Content:          feedbackMsg,
+		ReplyToMessageID: messageID,
+	})
+	if err != nil {
+		logger.WarnCF("voice", "Failed to send transcription feedback", map[string]any{"error": err.Error()})
+	}
+}

pkg/agent/loop_utils.go

@@ -0,0 +1,482 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+
+package agent
+
+import (
+	"context"
+	"fmt"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/commands"
+	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/session"
+	"github.com/sipeed/picoclaw/pkg/utils"
+)
+
+func outboundContextFromInbound(
+	inbound *bus.InboundContext,
+	channel, chatID, replyToMessageID string,
+) bus.InboundContext {
+	if inbound == nil {
+		return bus.NewOutboundContext(channel, chatID, replyToMessageID)
+	}
+
+	outboundCtx := *cloneInboundContext(inbound)
+	if outboundCtx.Channel == "" {
+		outboundCtx.Channel = channel
+	}
+	if outboundCtx.ChatID == "" {
+		outboundCtx.ChatID = chatID
+	}
+	if outboundCtx.ReplyToMessageID == "" {
+		outboundCtx.ReplyToMessageID = replyToMessageID
+	}
+	return outboundCtx
+}
+
+func outboundScopeFromSessionScope(scope *session.SessionScope) *bus.OutboundScope {
+	if scope == nil {
+		return nil
+	}
+	outboundScope := &bus.OutboundScope{
+		Version: scope.Version,
+		AgentID: scope.AgentID,
+		Channel: scope.Channel,
+		Account: scope.Account,
+	}
+	if len(scope.Dimensions) > 0 {
+		outboundScope.Dimensions = append([]string(nil), scope.Dimensions...)
+	}
+	if len(scope.Values) > 0 {
+		outboundScope.Values = make(map[string]string, len(scope.Values))
+		for key, value := range scope.Values {
+			outboundScope.Values[key] = value
+		}
+	}
+	return outboundScope
+}
+
+func outboundTurnMetadata(
+	agentID, sessionKey string,
+	scope *session.SessionScope,
+) (string, string, *bus.OutboundScope) {
+	return agentID, sessionKey, outboundScopeFromSessionScope(scope)
+}
+
+func outboundMessageForTurn(ts *turnState, content string) bus.OutboundMessage {
+	agentID, sessionKey, scope := outboundTurnMetadata(ts.agent.ID, ts.sessionKey, ts.opts.Dispatch.SessionScope)
+	return bus.OutboundMessage{
+		Channel: ts.channel,
+		ChatID:  ts.chatID,
+		Context: outboundContextFromInbound(
+			ts.opts.Dispatch.InboundContext,
+			ts.channel,
+			ts.chatID,
+			ts.opts.Dispatch.ReplyToMessageID(),
+		),
+		AgentID:    agentID,
+		SessionKey: sessionKey,
+		Scope:      scope,
+		Content:    content,
+	}
+}
+
+func cloneEventArguments(args map[string]any) map[string]any {
+	if len(args) == 0 {
+		return nil
+	}
+
+	cloned := make(map[string]any, len(args))
+	for k, v := range args {
+		cloned[k] = v
+	}
+	return cloned
+}
+
+func hookDeniedToolContent(prefix, reason string) string {
+	if reason == "" {
+		return prefix
+	}
+	return prefix + ": " + reason
+}
+
+func appendEventContextFields(fields map[string]any, turnCtx *TurnContext) {
+	if turnCtx == nil {
+		return
+	}
+
+	if inbound := turnCtx.Inbound; inbound != nil {
+		if inbound.Channel != "" {
+			fields["inbound_channel"] = inbound.Channel
+		}
+		if inbound.Account != "" {
+			fields["inbound_account"] = inbound.Account
+		}
+		if inbound.ChatID != "" {
+			fields["inbound_chat_id"] = inbound.ChatID
+		}
+		if inbound.ChatType != "" {
+			fields["inbound_chat_type"] = inbound.ChatType
+		}
+		if inbound.TopicID != "" {
+			fields["inbound_topic_id"] = inbound.TopicID
+		}
+		if inbound.SpaceType != "" {
+			fields["inbound_space_type"] = inbound.SpaceType
+		}
+		if inbound.SpaceID != "" {
+			fields["inbound_space_id"] = inbound.SpaceID
+		}
+		if inbound.SenderID != "" {
+			fields["inbound_sender_id"] = inbound.SenderID
+		}
+		if inbound.Mentioned {
+			fields["inbound_mentioned"] = true
+		}
+	}
+
+	if route := turnCtx.Route; route != nil {
+		if route.AgentID != "" {
+			fields["route_agent_id"] = route.AgentID
+		}
+		if route.Channel != "" {
+			fields["route_channel"] = route.Channel
+		}
+		if route.AccountID != "" {
+			fields["route_account_id"] = route.AccountID
+		}
+		if route.MatchedBy != "" {
+			fields["route_matched_by"] = route.MatchedBy
+		}
+		if len(route.SessionPolicy.Dimensions) > 0 {
+			fields["route_dimensions"] = strings.Join(route.SessionPolicy.Dimensions, ",")
+		}
+		if count := len(route.SessionPolicy.IdentityLinks); count > 0 {
+			fields["route_identity_link_count"] = count
+		}
+	}
+
+	if scope := turnCtx.Scope; scope != nil {
+		if scope.Version > 0 {
+			fields["scope_version"] = scope.Version
+		}
+		if scope.AgentID != "" {
+			fields["scope_agent_id"] = scope.AgentID
+		}
+		if scope.Channel != "" {
+			fields["scope_channel"] = scope.Channel
+		}
+		if scope.Account != "" {
+			fields["scope_account"] = scope.Account
+		}
+		if len(scope.Dimensions) > 0 {
+			fields["scope_dimensions"] = strings.Join(scope.Dimensions, ",")
+		}
+		for dim, value := range scope.Values {
+			if dim == "" || value == "" {
+				continue
+			}
+			fields["scope_"+dim] = value
+		}
+	}
+}
+
+func inferMediaType(filename, contentType string) string {
+	ct := strings.ToLower(contentType)
+	fn := strings.ToLower(filename)
+
+	if strings.HasPrefix(ct, "image/") {
+		return "image"
+	}
+	if strings.HasPrefix(ct, "audio/") || ct == "application/ogg" {
+		return "audio"
+	}
+	if strings.HasPrefix(ct, "video/") {
+		return "video"
+	}
+
+	// Fallback: infer from extension
+	ext := filepath.Ext(fn)
+	switch ext {
+	case ".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp", ".svg":
+		return "image"
+	case ".mp3", ".wav", ".ogg", ".m4a", ".flac", ".aac", ".wma", ".opus":
+		return "audio"
+	case ".mp4", ".avi", ".mov", ".webm", ".mkv":
+		return "video"
+	}
+
+	return "file"
+}
+
+func normalizedInboundContext(msg bus.InboundMessage) bus.InboundContext {
+	return bus.NormalizeInboundMessage(msg).Context
+}
+
+func resolveScopeKey(routeSessionKey, msgSessionKey string) string {
+	if isExplicitSessionKey(msgSessionKey) {
+		return msgSessionKey
+	}
+	return routeSessionKey
+}
+
+func isExplicitSessionKey(sessionKey string) bool {
+	return session.IsExplicitSessionKey(sessionKey)
+}
+
+func buildSessionAliases(canonicalKey string, keys ...string) []string {
+	if len(keys) == 0 {
+		return nil
+	}
+	aliases := make([]string, 0, len(keys))
+	seen := make(map[string]struct{}, len(keys))
+	canonicalKey = strings.TrimSpace(canonicalKey)
+	for _, key := range keys {
+		key = strings.TrimSpace(key)
+		if key == "" || key == canonicalKey {
+			continue
+		}
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		aliases = append(aliases, key)
+	}
+	if len(aliases) == 0 {
+		return nil
+	}
+	return aliases
+}
+
+func ensureSessionMetadata(store session.SessionStore, key string, scope *session.SessionScope, aliases []string) {
+	if key == "" || scope == nil {
+		return
+	}
+	metaStore, ok := store.(interface {
+		EnsureSessionMetadata(sessionKey string, scope *session.SessionScope, aliases []string)
+	})
+	if !ok {
+		return
+	}
+	metaStore.EnsureSessionMetadata(key, scope, aliases)
+}
+
+func sleepWithContext(ctx context.Context, d time.Duration) error {
+	timer := time.NewTimer(d)
+	defer timer.Stop()
+
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-timer.C:
+		return nil
+	}
+}
+
+func formatMessagesForLog(messages []providers.Message) string {
+	if len(messages) == 0 {
+		return "[]"
+	}
+
+	var sb strings.Builder
+	sb.WriteString("[\n")
+	for i, msg := range messages {
+		fmt.Fprintf(&sb, "  [%d] Role: %s\n", i, msg.Role)
+		if len(msg.ToolCalls) > 0 {
+			sb.WriteString("  ToolCalls:\n")
+			for _, tc := range msg.ToolCalls {
+				fmt.Fprintf(&sb, "    - ID: %s, Type: %s, Name: %s\n", tc.ID, tc.Type, tc.Name)
+				if tc.Function != nil {
+					fmt.Fprintf(
+						&sb,
+						"      Arguments: %s\n",
+						utils.Truncate(tc.Function.Arguments, 200),
+					)
+				}
+			}
+		}
+		if msg.Content != "" {
+			content := utils.Truncate(msg.Content, 200)
+			fmt.Fprintf(&sb, "  Content: %s\n", content)
+		}
+		if msg.ToolCallID != "" {
+			fmt.Fprintf(&sb, "  ToolCallID: %s\n", msg.ToolCallID)
+		}
+		sb.WriteString("\n")
+	}
+	sb.WriteString("]")
+	return sb.String()
+}
+
+func formatToolsForLog(toolDefs []providers.ToolDefinition) string {
+	if len(toolDefs) == 0 {
+		return "[]"
+	}
+
+	var sb strings.Builder
+	sb.WriteString("[\n")
+	for i, tool := range toolDefs {
+		fmt.Fprintf(&sb, "  [%d] Type: %s, Name: %s\n", i, tool.Type, tool.Function.Name)
+		fmt.Fprintf(&sb, "      Description: %s\n", tool.Function.Description)
+		if len(tool.Function.Parameters) > 0 {
+			fmt.Fprintf(
+				&sb,
+				"      Parameters: %s\n",
+				utils.Truncate(fmt.Sprintf("%v", tool.Function.Parameters), 200),
+			)
+		}
+	}
+	sb.WriteString("]")
+	return sb.String()
+}
+
+func activeSkillNames(agent *AgentInstance, opts processOptions) []string {
+	if agent == nil {
+		return nil
+	}
+
+	combined := make([]string, 0, len(agent.SkillsFilter)+len(opts.ForcedSkills))
+	combined = append(combined, agent.SkillsFilter...)
+	combined = append(combined, opts.ForcedSkills...)
+	if len(combined) == 0 {
+		return nil
+	}
+
+	var resolved []string
+	seen := make(map[string]struct{}, len(combined))
+	for _, name := range combined {
+		name = strings.TrimSpace(name)
+		if name == "" {
+			continue
+		}
+		if agent.ContextBuilder != nil {
+			if canonical, ok := agent.ContextBuilder.ResolveSkillName(name); ok {
+				name = canonical
+			}
+		}
+		key := strings.ToLower(name)
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		resolved = append(resolved, name)
+	}
+
+	return resolved
+}
+
+func sideQuestionResponseContent(response *providers.LLMResponse) string {
+	if response == nil {
+		return ""
+	}
+	if response.Content != "" {
+		return response.Content
+	}
+	return response.ReasoningContent
+}
+
+func shallowCloneLLMOptions(opts map[string]any) map[string]any {
+	clone := make(map[string]any, len(opts))
+	for k, v := range opts {
+		clone[k] = v
+	}
+	return clone
+}
+
+func hasMediaRefs(messages []providers.Message) bool {
+	for _, msg := range messages {
+		if len(msg.Media) > 0 {
+			return true
+		}
+	}
+	return false
+}
+
+func sideQuestionModelName(agent *AgentInstance, usedLight bool) string {
+	if usedLight && len(agent.LightCandidates) > 0 {
+		// Use the first light candidate's model
+		return agent.LightCandidates[0].Model
+	}
+	return agent.Model
+}
+
+func modelNameFromIdentityKey(identityKey string) string {
+	if identityKey == "" {
+		return ""
+	}
+	parts := strings.SplitN(identityKey, "/", 2)
+	if len(parts) == 2 {
+		return parts[1]
+	}
+	return identityKey
+}
+
+func closeProviderIfStateful(provider providers.LLMProvider) {
+	if stateful, ok := provider.(providers.StatefulProvider); ok {
+		stateful.Close()
+	}
+}
+
+func makePendingTurnID(sessionKey string, seq uint64) string {
+	return pendingTurnPrefix + sessionKey + "-" + fmt.Sprintf("%d", seq)
+}
+
+func commandsUnavailableSkillMessage() string {
+	return "Skill selection is unavailable in the current context."
+}
+
+func buildUseCommandHelp(agent *AgentInstance) string {
+	if agent == nil || agent.ContextBuilder == nil {
+		return "Usage: /use <skill> [message]"
+	}
+
+	names := agent.ContextBuilder.ListSkillNames()
+	if len(names) == 0 {
+		return "Usage: /use <skill> [message]\nNo installed skills found."
+	}
+
+	return fmt.Sprintf(
+		"Usage: /use <skill> [message]\n\nInstalled Skills:\n- %s\n\nUse /use <skill> to apply a skill to your next message, or /use <skill> <message> to force it immediately.",
+		strings.Join(names, "\n- "),
+	)
+}
+
+func mapCommandError(result commands.ExecuteResult) string {
+	if result.Command == "" {
+		return fmt.Sprintf("Failed to execute command: %v", result.Err)
+	}
+	return fmt.Sprintf("Failed to execute /%s: %v", result.Command, result.Err)
+}
+
+func isNativeSearchProvider(p providers.LLMProvider) bool {
+	if ns, ok := p.(providers.NativeSearchCapable); ok {
+		return ns.SupportsNativeSearch()
+	}
+	return false
+}
+
+func filterClientWebSearch(tools []providers.ToolDefinition) []providers.ToolDefinition {
+	result := make([]providers.ToolDefinition, 0, len(tools))
+	for _, t := range tools {
+		if strings.EqualFold(t.Function.Name, "web_search") {
+			continue
+		}
+		result = append(result, t)
+	}
+	return result
+}
+
+func extractProvider(registry *AgentRegistry) (providers.LLMProvider, bool) {
+	if registry == nil {
+		return nil, false
+	}
+	// Get any agent to access the provider
+	defaultAgent := registry.GetDefaultAgent()
+	if defaultAgent == nil {
+		return nil, false
+	}
+	return defaultAgent.Provider, true
+}