refactor: stabilize runtime and unify config

pkg/agent/loop.go

@@ -537,11 +537,11 @@ func nodeAgentTaskResult(payload map[string]interface{}) string {
 	if len(payload) == 0 {
 		return ""
 	}
-	if result, _ := payload["result"].(string); strings.TrimSpace(result) != "" {
-		return strings.TrimSpace(result)
+	if result := tools.MapStringArg(payload, "result"); result != "" {
+		return result
 	}
-	if content, _ := payload["content"].(string); strings.TrimSpace(content) != "" {
-		return strings.TrimSpace(content)
+	if content := tools.MapStringArg(payload, "content"); content != "" {
+		return content
 	}
 	return ""
 }
@@ -1804,8 +1804,8 @@ func (al *AgentLoop) buildProviderToolDefs(toolDefs []map[string]interface{}) []
 		if !ok {
 			continue
 		}
-		name, _ := fnRaw["name"].(string)
-		description, _ := fnRaw["description"].(string)
+		name := tools.MapStringArg(fnRaw, "name")
+		description := tools.MapStringArg(fnRaw, "description")
 		params, _ := fnRaw["parameters"].(map[string]interface{})
 		if strings.TrimSpace(name) == "" {
 			continue
@@ -1844,8 +1844,7 @@ func filterToolDefinitionsByContext(ctx context.Context, toolDefs []map[string]i
 		if !ok {
 			continue
 		}
-		name, _ := fnRaw["name"].(string)
-		name = strings.ToLower(strings.TrimSpace(name))
+		name := strings.ToLower(tools.MapStringArg(fnRaw, "name"))
 		if name == "" {
 			continue
 		}
@@ -2261,7 +2260,7 @@ func withToolMemoryNamespaceArgs(toolName string, args map[string]interface{}, n
 		return args
 	}
 
-	if raw, ok := args["namespace"].(string); ok && strings.TrimSpace(raw) != "" {
+	if raw := tools.MapStringArg(args, "namespace"); raw != "" {
 		return args
 	}
 	next := make(map[string]interface{}, len(args)+1)
@@ -2344,7 +2343,7 @@ func validateParallelAllowlistArgs(allow map[string]struct{}, args map[string]in
 		if !ok {
 			continue
 		}
-		tool, _ := m["tool"].(string)
+		tool := tools.MapStringArg(m, "tool")
 		name := strings.ToLower(strings.TrimSpace(tool))
 		if name == "" {
 			continue
@@ -2422,8 +2421,7 @@ func shouldSuppressSelfMessageSend(toolName string, args map[string]interface{},
 	if strings.TrimSpace(toolName) != "message" {
 		return false
 	}
-	action, _ := args["action"].(string)
-	action = strings.ToLower(strings.TrimSpace(action))
+	action := strings.ToLower(tools.MapStringArg(args, "action"))
 	if action == "" {
 		action = "send"
 	}
@@ -2436,17 +2434,15 @@ func shouldSuppressSelfMessageSend(toolName string, args map[string]interface{},
 }
 
 func resolveMessageToolTarget(args map[string]interface{}, fallbackChannel, fallbackChatID string) (string, string) {
-	channel, _ := args["channel"].(string)
-	channel = strings.TrimSpace(channel)
+	channel := tools.MapStringArg(args, "channel")
 	if channel == "" {
 		channel = strings.TrimSpace(fallbackChannel)
 	}
 
-	chatID, _ := args["chat_id"].(string)
-	if to, _ := args["to"].(string); strings.TrimSpace(to) != "" {
+	chatID := tools.MapStringArg(args, "chat_id")
+	if to := tools.MapStringArg(args, "to"); to != "" {
 		chatID = to
 	}
-	chatID = strings.TrimSpace(chatID)
 	if chatID == "" {
 		chatID = strings.TrimSpace(fallbackChatID)
 	}

pkg/agent/loop_allowlist_test.go

@@ -53,6 +53,15 @@ func TestEnsureToolAllowedByContextParallelNested(t *testing.T) {
 	if err := ensureToolAllowedByContext(restricted, "parallel", skillArgs); err != nil {
 		t.Fatalf("expected parallel with nested skill_exec to pass, got: %v", err)
 	}
+
+	stringToolArgs := map[string]interface{}{
+		"calls": []interface{}{
+			map[string]interface{}{"tool": "read_file", "arguments": map[string]interface{}{"path": "README.md"}},
+		},
+	}
+	if err := ensureToolAllowedByContext(restricted, "parallel", stringToolArgs); err != nil {
+		t.Fatalf("expected parallel with string tool key to pass, got: %v", err)
+	}
 }
 
 func TestEnsureToolAllowedByContext_GroupAllowlist(t *testing.T) {

pkg/agent/loop_message_target_test.go

@@ -0,0 +1,30 @@
+package agent
+
+import "testing"
+
+func TestResolveMessageToolTargetUsesStringHelpers(t *testing.T) {
+	channel, chat := resolveMessageToolTarget(map[string]interface{}{
+		"channel": "telegram",
+		"to":      "chat-2",
+	}, "whatsapp", "chat-1")
+	if channel != "telegram" || chat != "chat-2" {
+		t.Fatalf("unexpected target: %s %s", channel, chat)
+	}
+
+	channel, chat = resolveMessageToolTarget(map[string]interface{}{}, "whatsapp", "chat-1")
+	if channel != "whatsapp" || chat != "chat-1" {
+		t.Fatalf("unexpected fallback target: %s %s", channel, chat)
+	}
+}
+
+func TestNodeAgentTaskResultUsesCompatiblePayloadFields(t *testing.T) {
+	if got := nodeAgentTaskResult(map[string]interface{}{"result": "done"}); got != "done" {
+		t.Fatalf("unexpected result field extraction: %q", got)
+	}
+	if got := nodeAgentTaskResult(map[string]interface{}{"content": "fallback"}); got != "fallback" {
+		t.Fatalf("unexpected content field extraction: %q", got)
+	}
+	if got := nodeAgentTaskResult(nil); got != "" {
+		t.Fatalf("expected empty result for nil payload, got %q", got)
+	}
+}

pkg/agent/router_dispatch.go

@@ -27,8 +27,8 @@ func (al *AgentLoop) maybeAutoRoute(ctx context.Context, msg bus.InboundMessage)
 	if cfg == nil || !cfg.Agents.Router.Enabled {
 		return "", false, nil
 	}
-	agentID, taskText := resolveAutoRouteTarget(cfg, msg.Content)
-	if agentID == "" || strings.TrimSpace(taskText) == "" {
+	decision := resolveDispatchDecision(cfg, msg.Content)
+	if !decision.Valid() {
 		return "", false, nil
 	}
 	waitTimeout := cfg.Agents.Router.DefaultTimeoutSec
@@ -38,8 +38,9 @@ func (al *AgentLoop) maybeAutoRoute(ctx context.Context, msg bus.InboundMessage)
 	waitCtx, cancel := context.WithTimeout(ctx, time.Duration(waitTimeout)*time.Second)
 	defer cancel()
 	task, err := al.subagentRouter.DispatchTask(waitCtx, tools.RouterDispatchRequest{
-		Task:             taskText,
-		AgentID:          agentID,
+		Task:             decision.TaskText,
+		AgentID:          decision.TargetAgent,
+		Decision:         &decision,
 		NotifyMainPolicy: "internal_only",
 		OriginChannel:    msg.Channel,
 		OriginChatID:     msg.ChatID,
@@ -55,16 +56,21 @@ func (al *AgentLoop) maybeAutoRoute(ctx context.Context, msg bus.InboundMessage)
 }
 
 func resolveAutoRouteTarget(cfg *config.Config, raw string) (string, string) {
+	decision := resolveDispatchDecision(cfg, raw)
+	return decision.TargetAgent, decision.TaskText
+}
+
+func resolveDispatchDecision(cfg *config.Config, raw string) tools.DispatchDecision {
 	if cfg == nil {
-		return "", ""
+		return tools.DispatchDecision{}
 	}
 	content := strings.TrimSpace(raw)
 	if content == "" || len(cfg.Agents.Subagents) == 0 {
-		return "", ""
+		return tools.DispatchDecision{}
 	}
 	maxChars := cfg.Agents.Router.Policy.IntentMaxInputChars
 	if maxChars > 0 && len([]rune(content)) > maxChars {
-		return "", ""
+		return tools.DispatchDecision{}
 	}
 	lower := strings.ToLower(content)
 	for agentID, subcfg := range cfg.Agents.Subagents {
@@ -73,19 +79,37 @@ func resolveAutoRouteTarget(cfg *config.Config, raw string) (string, string) {
 		}
 		marker := "@" + strings.ToLower(strings.TrimSpace(agentID))
 		if strings.HasPrefix(lower, marker+" ") || lower == marker {
-			return agentID, strings.TrimSpace(content[len(marker):])
+			return tools.DispatchDecision{
+				TargetAgent: agentID,
+				Reason:      "explicit agent mention",
+				Confidence:  1,
+				TaskText:    strings.TrimSpace(content[len(marker):]),
+				RouteSource: "explicit",
+			}
 		}
 		prefix := "agent:" + strings.ToLower(strings.TrimSpace(agentID))
 		if strings.HasPrefix(lower, prefix+" ") || lower == prefix {
-			return agentID, strings.TrimSpace(content[len(prefix):])
+			return tools.DispatchDecision{
+				TargetAgent: agentID,
+				Reason:      "explicit agent prefix",
+				Confidence:  1,
+				TaskText:    strings.TrimSpace(content[len(prefix):]),
+				RouteSource: "explicit",
+			}
 		}
 	}
 	if strings.EqualFold(strings.TrimSpace(cfg.Agents.Router.Strategy), "rules_first") {
 		if agentID := selectAgentByRules(cfg, content); agentID != "" {
-			return agentID, content
+			return tools.DispatchDecision{
+				TargetAgent: agentID,
+				Reason:      "matched router rules or role keywords",
+				Confidence:  0.8,
+				TaskText:    content,
+				RouteSource: "rules",
+			}
 		}
 	}
-	return "", ""
+	return tools.DispatchDecision{}
 }
 
 func selectAgentByRules(cfg *config.Config, content string) string {

pkg/agent/router_dispatch_test.go

@@ -29,7 +29,7 @@ func TestResolveAutoRouteTargetRulesFirst(t *testing.T) {
 	cfg.Agents.Subagents["tester"] = config.SubagentConfig{Enabled: true, Role: "testing", SystemPromptFile: "agents/tester/AGENT.md"}
 	cfg.Agents.Router.Rules = []config.AgentRouteRule{{AgentID: "coder", Keywords: []string{"鐧诲綍", "bug"}}}
 
-	agentID, task := resolveAutoRouteTarget(cfg, "璇峰府鎴戜慨澶嶇櫥褰曟帴鍙ｇ殑 bug 骞舵敼浠ｇ爜")
+	agentID, task := resolveAutoRouteTarget(cfg, "please fix the login bug and update the code")
 	if agentID != "coder" || task == "" {
 		t.Fatalf("expected coder route, got %s / %s", agentID, task)
 	}
@@ -113,7 +113,7 @@ func TestMaybeAutoRouteDispatchesRulesFirstMatch(t *testing.T) {
 		Channel:    "cli",
 		ChatID:     "direct",
 		SessionKey: "main",
-		Content:    "璇峰仛涓€娆″洖褰掓祴璇曞苟楠岃瘉杩欎釜淇",
+		Content:    "please run regression testing and verify this fix",
 	})
 	if err != nil {
 		t.Fatalf("rules-first auto route failed: %v", err)
@@ -126,6 +126,21 @@ func TestMaybeAutoRouteDispatchesRulesFirstMatch(t *testing.T) {
 	}
 }
 
+func TestResolveDispatchDecisionIncludesReason(t *testing.T) {
+	cfg := config.DefaultConfig()
+	cfg.Agents.Router.Enabled = true
+	cfg.Agents.Router.Strategy = "rules_first"
+	cfg.Agents.Subagents["tester"] = config.SubagentConfig{Enabled: true, Role: "testing", SystemPromptFile: "agents/tester/AGENT.md"}
+
+	decision := resolveDispatchDecision(cfg, "run regression testing for this change")
+	if !decision.Valid() {
+		t.Fatalf("expected valid decision")
+	}
+	if decision.TargetAgent != "tester" || decision.RouteSource == "" || decision.Reason == "" {
+		t.Fatalf("unexpected decision: %+v", decision)
+	}
+}
+
 func TestResolveAutoRouteTargetSkipsOversizedIntent(t *testing.T) {
 	cfg := config.DefaultConfig()
 	cfg.Agents.Router.Enabled = true

pkg/agent/runtime_admin.go

@@ -38,6 +38,9 @@ func (al *AgentLoop) HandleSubagentRuntime(ctx context.Context, action string, a
 		}
 		sort.Slice(items, func(i, j int) bool { return items[i].Created > items[j].Created })
 		return map[string]interface{}{"items": items}, nil
+	case "snapshot":
+		limit := runtimeIntArg(args, "limit", 100)
+		return map[string]interface{}{"snapshot": sm.RuntimeSnapshot(limit)}, nil
 	case "get", "info":
 		taskID, err := resolveSubagentTaskIDForRuntime(sm, runtimeStringArg(args, "id"))
 		if err != nil {
@@ -194,7 +197,7 @@ func (al *AgentLoop) HandleSubagentRuntime(ctx context.Context, action string, a
 		if al.isProtectedMainAgent(agentID) {
 			return nil, fmt.Errorf("main agent %q cannot be disabled", agentID)
 		}
-		enabled, ok := args["enabled"].(bool)
+		enabled, ok := runtimeBoolArg(args, "enabled")
 		if !ok {
 			return nil, fmt.Errorf("enabled is required")
 		}
@@ -400,22 +403,6 @@ func (al *AgentLoop) HandleSubagentRuntime(ctx context.Context, action string, a
 			"thread": thread,
 			"items":  stream,
 		}, nil
-	case "stream_all":
-		tasks := sm.ListTasks()
-		sort.Slice(tasks, func(i, j int) bool {
-			left := maxInt64(tasks[i].Updated, tasks[i].Created)
-			right := maxInt64(tasks[j].Updated, tasks[j].Created)
-			if left != right {
-				return left > right
-			}
-			return tasks[i].ID > tasks[j].ID
-		})
-		taskLimit := runtimeIntArg(args, "task_limit", 16)
-		if taskLimit > 0 && len(tasks) > taskLimit {
-			tasks = tasks[:taskLimit]
-		}
-		items := mergeAllSubagentStreams(sm, tasks, runtimeIntArg(args, "limit", 200))
-		return map[string]interface{}{"found": true, "items": items}, nil
 	case "inbox":
 		agentID := runtimeStringArg(args, "agent_id")
 		if agentID == "" {
@@ -528,90 +515,6 @@ func mergeSubagentStream(events []tools.SubagentRunEvent, messages []tools.Agent
 	return items
 }
 
-func mergeAllSubagentStreams(sm *tools.SubagentManager, tasks []*tools.SubagentTask, limit int) []map[string]interface{} {
-	if sm == nil || len(tasks) == 0 {
-		return nil
-	}
-	items := make([]map[string]interface{}, 0)
-	seenEvents := map[string]struct{}{}
-	seenMessages := map[string]struct{}{}
-	for _, task := range tasks {
-		if task == nil {
-			continue
-		}
-		if events, err := sm.Events(task.ID, limit); err == nil {
-			for _, evt := range events {
-				key := fmt.Sprintf("%s:%s:%d:%s", evt.RunID, evt.Type, evt.At, evt.Message)
-				if _, ok := seenEvents[key]; ok {
-					continue
-				}
-				seenEvents[key] = struct{}{}
-				items = append(items, map[string]interface{}{
-					"kind":        "event",
-					"at":          evt.At,
-					"task_id":     task.ID,
-					"label":       task.Label,
-					"run_id":      evt.RunID,
-					"agent_id":    firstNonEmptyString(evt.AgentID, task.AgentID),
-					"event_type":  evt.Type,
-					"status":      evt.Status,
-					"message":     evt.Message,
-					"retry_count": evt.RetryCount,
-				})
-			}
-		}
-		if strings.TrimSpace(task.ThreadID) == "" {
-			continue
-		}
-		if messages, err := sm.ThreadMessages(task.ThreadID, limit); err == nil {
-			for _, msg := range messages {
-				if _, ok := seenMessages[msg.MessageID]; ok {
-					continue
-				}
-				seenMessages[msg.MessageID] = struct{}{}
-				items = append(items, map[string]interface{}{
-					"kind":           "message",
-					"at":             msg.CreatedAt,
-					"task_id":        task.ID,
-					"label":          task.Label,
-					"message_id":     msg.MessageID,
-					"thread_id":      msg.ThreadID,
-					"from_agent":     msg.FromAgent,
-					"to_agent":       msg.ToAgent,
-					"reply_to":       msg.ReplyTo,
-					"correlation_id": msg.CorrelationID,
-					"message_type":   msg.Type,
-					"content":        msg.Content,
-					"status":         msg.Status,
-					"requires_reply": msg.RequiresReply,
-				})
-			}
-		}
-	}
-	sort.Slice(items, func(i, j int) bool {
-		left, _ := items[i]["at"].(int64)
-		right, _ := items[j]["at"].(int64)
-		if left != right {
-			return left < right
-		}
-		return fmt.Sprintf("%v", items[i]["task_id"]) < fmt.Sprintf("%v", items[j]["task_id"])
-	})
-	if limit > 0 && len(items) > limit {
-		items = items[len(items)-limit:]
-	}
-	return items
-}
-
-func maxInt64(values ...int64) int64 {
-	var out int64
-	for _, v := range values {
-		if v > out {
-			out = v
-		}
-	}
-	return out
-}
-
 func firstNonEmptyString(values ...string) string {
 	for _, v := range values {
 		if strings.TrimSpace(v) != "" {
@@ -665,40 +568,19 @@ func resolveSubagentTaskIDForRuntime(sm *tools.SubagentManager, raw string) (str
 }
 
 func runtimeStringArg(args map[string]interface{}, key string) string {
-	if args == nil {
-		return ""
-	}
-	v, _ := args[key].(string)
-	return strings.TrimSpace(v)
+	return tools.MapStringArg(args, key)
 }
 
 func runtimeRawStringArg(args map[string]interface{}, key string) string {
-	if args == nil {
-		return ""
-	}
-	v, _ := args[key].(string)
-	return v
+	return tools.MapRawStringArg(args, key)
 }
 
 func runtimeIntArg(args map[string]interface{}, key string, fallback int) int {
-	if args == nil {
-		return fallback
-	}
-	switch v := args[key].(type) {
-	case int:
-		if v > 0 {
-			return v
-		}
-	case int64:
-		if v > 0 {
-			return int(v)
-		}
-	case float64:
-		if v > 0 {
-			return int(v)
-		}
-	}
-	return fallback
+	return tools.MapIntArg(args, key, fallback)
+}
+
+func runtimeBoolArg(args map[string]interface{}, key string) (bool, bool) {
+	return tools.MapBoolArg(args, key)
 }
 
 func fallbackString(v, fallback string) string {

pkg/agent/runtime_admin_test.go

@@ -48,6 +48,7 @@ func TestHandleSubagentRuntimeDispatchAndWait(t *testing.T) {
 	if merged == "" {
 		t.Fatalf("expected merged output")
 	}
+	time.Sleep(20 * time.Millisecond)
 }
 
 func TestHandleSubagentRuntimeUpsertConfigSubagent(t *testing.T) {
@@ -247,6 +248,50 @@ func TestHandleSubagentRuntimeDeleteConfigSubagent(t *testing.T) {
 	}
 }
 
+func TestHandleSubagentRuntimeToggleEnabledParsesStringBool(t *testing.T) {
+	workspace := t.TempDir()
+	configPath := filepath.Join(workspace, "config.json")
+	cfg := config.DefaultConfig()
+	cfg.Agents.Router.Enabled = true
+	cfg.Agents.Subagents["main"] = config.SubagentConfig{
+		Enabled:          true,
+		Type:             "router",
+		Role:             "orchestrator",
+		SystemPromptFile: "agents/main/AGENT.md",
+	}
+	cfg.Agents.Subagents["tester"] = config.SubagentConfig{
+		Enabled:          true,
+		Type:             "worker",
+		Role:             "testing",
+		SystemPromptFile: "agents/tester/AGENT.md",
+	}
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("save config failed: %v", err)
+	}
+	runtimecfg.Set(cfg)
+	t.Cleanup(func() { runtimecfg.Set(config.DefaultConfig()) })
+
+	manager := tools.NewSubagentManager(nil, workspace, nil)
+	loop := &AgentLoop{
+		configPath:      configPath,
+		subagentManager: manager,
+		subagentRouter:  tools.NewSubagentRouter(manager),
+	}
+	if _, err := loop.HandleSubagentRuntime(context.Background(), "set_config_subagent_enabled", map[string]interface{}{
+		"agent_id": "tester",
+		"enabled":  "false",
+	}); err != nil {
+		t.Fatalf("toggle enabled failed: %v", err)
+	}
+	reloaded, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("reload config failed: %v", err)
+	}
+	if reloaded.Agents.Subagents["tester"].Enabled {
+		t.Fatalf("expected tester to be disabled")
+	}
+}
+
 func TestHandleSubagentRuntimePromptFileGetSetBootstrap(t *testing.T) {
 	workspace := t.TempDir()
 	manager := tools.NewSubagentManager(nil, workspace, nil)
@@ -437,19 +482,4 @@ func TestHandleSubagentRuntimeStreamAll(t *testing.T) {
 		time.Sleep(10 * time.Millisecond)
 	}
 
-	out, err := loop.HandleSubagentRuntime(context.Background(), "stream_all", map[string]interface{}{
-		"limit":      100,
-		"task_limit": 10,
-	})
-	if err != nil {
-		t.Fatalf("stream_all failed: %v", err)
-	}
-	payload, ok := out.(map[string]interface{})
-	if !ok || payload["found"] != true {
-		t.Fatalf("unexpected stream_all payload: %#v", out)
-	}
-	items, ok := payload["items"].([]map[string]interface{})
-	if !ok || len(items) == 0 {
-		t.Fatalf("expected grouped stream items, got %#v", payload["items"])
-	}
 }