chore: refine error diagnostics

Author: voocel

internal/agent/runtime_metrics.go

@@ -1,6 +1,18 @@
 package agent
 
-import "time"
+import (
+	"strings"
+	"time"
+
+	"github.com/voocel/codebot/internal/apperr"
+)
+
+type ErrorSnapshot struct {
+	Kind      apperr.Kind
+	Message   string
+	Detail    string
+	Timestamp time.Time
+}
 
 type RuntimeMetricsSnapshot struct {
 	ReminderTotal         int
@@ -10,6 +22,8 @@ type RuntimeMetricsSnapshot struct {
 	CompactionSaved       int
 	CompactionByKind      map[CompactionKind]int
 	CompactionSavedByKind map[CompactionKind]int
+	ErrorTotal            int
+	ErrorByKind           map[apperr.Kind]int
 }
 
 type runtimeMetrics struct {
@@ -20,13 +34,16 @@ type runtimeMetrics struct {
 	compactionSaved       int
 	compactionByKind      map[CompactionKind]int
 	compactionSavedByKind map[CompactionKind]int
+	errorTotal            int
+	errorByKind           map[apperr.Kind]int
 }
 
 func newRuntimeMetrics() *runtimeMetrics {
 	return &runtimeMetrics{
 		reminderByKind:        make(map[RuntimeReminderKind]int),
 		compactionByKind:      make(map[CompactionKind]int),
 		compactionSavedByKind: make(map[CompactionKind]int),
+		errorByKind:           make(map[apperr.Kind]int),
 	}
 }
 
@@ -46,6 +63,10 @@ func (s *Session) RuntimeMetrics() RuntimeMetricsSnapshot {
 	for k, v := range s.metrics.compactionSavedByKind {
 		compactionSavedByKind[k] = v
 	}
+	errorByKind := make(map[apperr.Kind]int, len(s.metrics.errorByKind))
+	for k, v := range s.metrics.errorByKind {
+		errorByKind[k] = v
+	}
 	return RuntimeMetricsSnapshot{
 		ReminderTotal:         s.metrics.reminderTotal,
 		ReminderByKind:        reminderByKind,
@@ -54,6 +75,8 @@ func (s *Session) RuntimeMetrics() RuntimeMetricsSnapshot {
 		CompactionSaved:       s.metrics.compactionSaved,
 		CompactionByKind:      compactionByKind,
 		CompactionSavedByKind: compactionSavedByKind,
+		ErrorTotal:            s.metrics.errorTotal,
+		ErrorByKind:           errorByKind,
 	}
 }
 
@@ -119,3 +142,57 @@ func (s *Session) recordCompactionSnapshot(kind CompactionKind, strategy, reason
 		Timestamp:      time.Now(),
 	}
 }
+
+func (s *Session) recordErrorDiagnostic(err error) {
+	if err == nil {
+		return
+	}
+
+	snapshot := buildErrorSnapshot(err)
+
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if s.metrics == nil {
+		s.metrics = newRuntimeMetrics()
+	}
+	s.metrics.errorTotal++
+	s.metrics.errorByKind[snapshot.Kind]++
+
+	s.recentErrors = append(s.recentErrors, snapshot)
+	if len(s.recentErrors) > maxRecentErrors {
+		s.recentErrors = append([]ErrorSnapshot(nil), s.recentErrors[len(s.recentErrors)-maxRecentErrors:]...)
+	}
+}
+
+func buildErrorSnapshot(err error) ErrorSnapshot {
+	message := strings.TrimSpace(apperr.Format(err, ""))
+	if message == "" {
+		message = "error"
+	}
+	detail := strings.TrimSpace(err.Error())
+	if detail == message {
+		detail = ""
+	} else if strings.HasPrefix(detail, message+": ") {
+		detail = strings.TrimSpace(strings.TrimPrefix(detail, message+": "))
+	}
+	return ErrorSnapshot{
+		Kind:      apperr.KindOf(err),
+		Message:   message,
+		Detail:    detail,
+		Timestamp: time.Now(),
+	}
+}
+
+func (s *Session) RecentErrors(limit int) []ErrorSnapshot {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if limit <= 0 || limit > len(s.recentErrors) {
+		limit = len(s.recentErrors)
+	}
+	start := len(s.recentErrors) - limit
+	snapshots := make([]ErrorSnapshot, limit)
+	copy(snapshots, s.recentErrors[start:])
+	return snapshots
+}

internal/agent/runtime_policy.go

@@ -15,6 +15,7 @@ import (
 
 const (
 	maxRecentToolCalls        = 8
+	maxRecentErrors           = 10
 	repeatedToolCallThreshold = 4
 )
 

internal/agent/session.go

@@ -115,6 +115,7 @@ type Session struct {
 	lastRunSummary          *agentcore.RunSummary
 	lastReminder            *ReminderSnapshot
 	lastCompaction          *CompactionSnapshot
+	recentErrors            []ErrorSnapshot
 	dirtySeq                uint64 // incremented each time a repo-mutating tool succeeds; hook goroutine captures this and only clears if unchanged
 	generation              uint64 // incremented on session switch; async goroutines check this to avoid cross-session callbacks
 
@@ -235,6 +236,7 @@ func (s *Session) resetHarnessStateLocked() {
 	s.lastRunSummary = nil
 	s.lastReminder = nil
 	s.lastCompaction = nil
+	s.recentErrors = nil
 	s.dirtySeq = 0
 	s.metrics = newRuntimeMetrics()
 	s.skillRuntime = skillRuntimeState{}

internal/agent/session_state.go

@@ -93,6 +93,15 @@ func (s *Session) handleAgentEvent(ev agentcore.Event) {
 }
 
 func (s *Session) emit(ev SessionEvent) {
+	switch ev.Type {
+	case SEError:
+		s.recordErrorDiagnostic(ev.Error)
+	case SEAgentEvent:
+		if ev.AgentEvent != nil && ev.AgentEvent.Type == agentcore.EventError {
+			s.recordErrorDiagnostic(ev.AgentEvent.Err)
+		}
+	}
+
 	s.mu.Lock()
 	listeners := make([]func(SessionEvent), len(s.listeners))
 	copy(listeners, s.listeners)

internal/apperr/errors.go

@@ -1,10 +1,24 @@
 package apperr
 
 import (
+	"context"
 	"errors"
 	"fmt"
 )
 
+type Kind string
+
+const (
+	KindUnknown    Kind = ""
+	KindCanceled   Kind = "canceled"
+	KindConfig     Kind = "config"
+	KindPermission Kind = "permission"
+	KindProvider   Kind = "provider"
+	KindSession    Kind = "session"
+	KindToolInput  Kind = "tool_input"
+	KindToolExec   Kind = "tool_exec"
+)
+
 // UserError exposes a concise user-facing message while preserving the full
 // wrapped error for logging and debugging.
 type UserError interface {
@@ -14,6 +28,7 @@ type UserError interface {
 
 type Error struct {
 	Display string
+	Kind    Kind
 	Err     error
 }
 
@@ -41,18 +56,58 @@ func (e *Error) DisplayMessage() string {
 	return e.Display
 }
 
+func (e *Error) ErrorKind() Kind {
+	if e == nil {
+		return KindUnknown
+	}
+	return e.Kind
+}
+
 func New(display string) error {
 	return &Error{Display: display}
 }
 
+func NewKind(kind Kind, display string) error {
+	return &Error{Display: display, Kind: kind}
+}
+
 func Newf(format string, args ...any) error {
 	return &Error{Display: fmt.Sprintf(format, args...)}
 }
 
+func NewKindf(kind Kind, format string, args ...any) error {
+	return &Error{Display: fmt.Sprintf(format, args...), Kind: kind}
+}
+
 func Wrap(display string, err error) error {
 	return &Error{Display: display, Err: err}
 }
 
+func WrapKind(kind Kind, display string, err error) error {
+	return &Error{Display: display, Kind: kind, Err: err}
+}
+
+func KindOf(err error) Kind {
+	original := err
+	for err != nil {
+		type kindCarrier interface {
+			ErrorKind() Kind
+		}
+		if carrier, ok := err.(kindCarrier); ok && carrier.ErrorKind() != KindUnknown {
+			return carrier.ErrorKind()
+		}
+		err = errors.Unwrap(err)
+	}
+	if errors.Is(original, context.Canceled) {
+		return KindCanceled
+	}
+	return KindUnknown
+}
+
+func IsKind(err error, kind Kind) bool {
+	return KindOf(err) == kind
+}
+
 func Format(err error, fallbackPrefix string) string {
 	if err == nil {
 		return ""

internal/bootstrap/assemble_session.go

@@ -7,6 +7,7 @@ import (
 
 	"github.com/voocel/agentcore"
 	agentcoretools "github.com/voocel/agentcore/tools"
+	"github.com/voocel/codebot/internal/apperr"
 	"github.com/voocel/codebot/internal/approval"
 	"github.com/voocel/codebot/internal/config"
 	"github.com/voocel/codebot/internal/hooks"
@@ -84,7 +85,7 @@ func resolveActiveModel(input *resolvedInput) (config.Resolved, string, agentcor
 	}
 	chatModel, err := input.modelFactory(provType, activeModel, activeAPIKey, activeBaseURL)
 	if err != nil {
-		return config.Resolved{}, "", nil, fmt.Errorf("create model: %w", err)
+		return config.Resolved{}, "", nil, apperr.WrapKind(apperr.KindProvider, "create model failed", err)
 	}
 
 	settings := input.settings

internal/bootstrap/input.go

@@ -66,15 +66,15 @@ func resolveInput(opts Options) (*resolvedInput, error) {
 	sessionManager := storage.NewManager(config.SessionsDir(cwd))
 	sessionStore, err := resolveSession(sessionManager, cwd, opts.Continue, opts.Resume, opts.NonTTYMode)
 	if err != nil {
-		return nil, fmt.Errorf("session: %w", err)
+		return nil, apperr.WrapKind(apperr.KindSession, "session setup failed", err)
 	}
 
 	var sessionSnapshot storage.ContextSnapshot
 	if opts.Continue || opts.Resume {
 		sessionSnapshot, err = sessionStore.BuildSnapshot()
 		if err != nil {
 			_ = sessionStore.Close()
-			return nil, fmt.Errorf("restore context: %w", err)
+			return nil, apperr.WrapKind(apperr.KindSession, "restore context failed", err)
 		}
 	}
 
@@ -98,7 +98,7 @@ func ensureProviderSetup(cwd string, settings config.Resolved, nonTTY bool) (con
 		if hasConfiguredProviderCredentials(settings, settings.Provider) {
 			return settings, "", nil
 		}
-		return settings, "", apperr.Newf("configuration error: settings.provider=%q is missing or not configured in settings.json", settings.Provider)
+		return settings, "", apperr.NewKindf(apperr.KindConfig, "configuration error: settings.provider=%q is missing or not configured in settings.json", settings.Provider)
 	}
 
 	apiKey, _ := settings.ProviderCredentials(settings.Provider)
@@ -114,12 +114,12 @@ func ensureProviderSetup(cwd string, settings config.Resolved, nonTTY bool) (con
 	}
 
 	if nonTTY {
-		return settings, "", fmt.Errorf("api key not set; set %s or configure providers in %s",
+		return settings, "", apperr.NewKindf(apperr.KindConfig, "api key not set; set %s or configure providers in %s",
 			config.ProviderEnvKey(settings.Provider), filepath.Join(config.UserConfigDir(), "settings.json"))
 	}
 
 	if err := config.RunSetup(settings); err != nil {
-		return settings, "", fmt.Errorf("setup: %w", err)
+		return settings, "", apperr.WrapKind(apperr.KindConfig, "setup failed", err)
 	}
 	resolved, err := config.ResolveAllStrict(cwd)
 	if err != nil {
@@ -160,7 +160,7 @@ func resolveSession(mgr *storage.Manager, cwd string, cont, resume, nonTTY bool)
 			return mgr.Create(cwd)
 		}
 		if nonTTY {
-			return nil, fmt.Errorf("-r requires interactive terminal, use -c or -session in non-interactive mode")
+			return nil, apperr.NewKind(apperr.KindSession, "-r requires interactive terminal, use -c or -session in non-interactive mode")
 		}
 
 		fmt.Fprintf(os.Stderr, "Available sessions:\n")
@@ -177,11 +177,11 @@ func resolveSession(mgr *storage.Manager, cwd string, cont, resume, nonTTY bool)
 		reader := bufio.NewReader(os.Stdin)
 		raw, err := reader.ReadString('\n')
 		if err != nil && !errors.Is(err, io.EOF) {
-			return nil, fmt.Errorf("read session selection: %w", err)
+			return nil, apperr.WrapKind(apperr.KindSession, "read session selection failed", err)
 		}
 		choice := strings.TrimSpace(raw)
 		if choice == "" {
-			return nil, fmt.Errorf("no session selected")
+			return nil, apperr.NewKind(apperr.KindSession, "no session selected")
 		}
 
 		for _, s := range sessions {
@@ -192,11 +192,11 @@ func resolveSession(mgr *storage.Manager, cwd string, cont, resume, nonTTY bool)
 
 		if idx, convErr := strconv.Atoi(choice); convErr == nil {
 			if idx < 1 || idx > len(sessions) {
-				return nil, fmt.Errorf("invalid session index %d (range: 1-%d)", idx, len(sessions))
+				return nil, apperr.NewKindf(apperr.KindSession, "invalid session index %d (range: 1-%d)", idx, len(sessions))
 			}
 			return mgr.OpenPath(sessions[idx-1].Path)
 		}
-		return nil, fmt.Errorf("invalid session selection %q", choice)
+		return nil, apperr.NewKindf(apperr.KindSession, "invalid session selection %q", choice)
 	default:
 		return mgr.Create(cwd)
 	}

internal/config/settings.go

@@ -47,12 +47,12 @@ func ResolveProviderType(name, explicitType string) (string, error) {
 		if provider.IsSupportedType(provType) {
 			return provType, nil
 		}
-		return "", apperr.Newf("configuration error: providers.%s.type=%q is unsupported", name, explicitType)
+		return "", apperr.NewKindf(apperr.KindConfig, "configuration error: providers.%s.type=%q is unsupported", name, explicitType)
 	}
 	if t, ok := KnownProviderTypes[name]; ok {
 		return t, nil
 	}
-	return "", apperr.Newf("configuration error: providers.%s.type is required for custom providers", name)
+	return "", apperr.NewKindf(apperr.KindConfig, "configuration error: providers.%s.type is required for custom providers", name)
 }
 
 // ResolveConfiguredProviderType resolves the protocol type for a configured provider.
@@ -502,7 +502,7 @@ func loadSettingsFileStrict(path string) (Settings, error) {
 		return s, err
 	}
 	if err := json.Unmarshal(data, &s); err != nil {
-		return s, apperr.Wrap("configuration error: malformed settings.json", fmt.Errorf("%s: %w", path, err))
+		return s, apperr.WrapKind(apperr.KindConfig, "configuration error: malformed settings.json", fmt.Errorf("%s: %w", path, err))
 	}
 	return s, nil
 }

internal/provider/provider.go

@@ -1,12 +1,12 @@
 package provider
 
 import (
-	"fmt"
 	"slices"
 	"strings"
 
 	"github.com/voocel/agentcore"
 	"github.com/voocel/agentcore/llm"
+	"github.com/voocel/codebot/internal/apperr"
 )
 
 var supportedTypeNames = []string{"openai", "anthropic", "gemini", "openrouter"}
@@ -65,7 +65,7 @@ func CreateModel(prov, name, apiKey, baseURL string) (agentcore.ChatModel, error
 func newProviderModel(prov, name, apiKey, baseURL string) (agentcore.ChatModel, error) {
 	factory, ok := modelFactories[prov]
 	if !ok {
-		return nil, fmt.Errorf("unsupported provider type %q", prov)
+		return nil, apperr.NewKindf(apperr.KindProvider, "unsupported provider type %q", prov)
 	}
 	return factory(name, apiKey, baseURL)
 }