# Understanding the Agentsview Signal Classification System: A Technical Deep Dive

> Explore the Agentsview signal classification system. This Go framework enriches AI sessions with outcome status, quality scores, and tool health metrics for machine readability. Learn more.

- Repository: [Kenn Software/agentsview](https://github.com/kenn-io/agentsview)
- Tags: deep-dive
- Published: 2026-06-20

---

**Agentsview implements a lightweight, pure-Go signal classification framework that automatically enriches every stored AI session with machine-readable annotations including outcome status, quality scores, and tool health metrics.**

The `kenn-io/agentsview` repository uses this system to transform raw session transcripts into actionable metadata stored in SQLite (or optionally PostgreSQL). By applying deterministic algorithms at sync time, the agentsview signal classification system enables powerful filtering, sorting, and analytics without requiring manual tagging.

## Core Signal Types

The classification system defines four primary signal categories, each implemented as a pure function in the `internal/signals/` package. These functions receive structured session data and return deterministic results without database access.

### Outcome Signal

The **Outcome** signal determines whether a session finished as `completed`, `abandoned`, `errored`, or `unknown`, along with a confidence level and recency flag. This logic resides in [[`internal/signals/outcome.go`](https://github.com/kenn-io/agentsview/blob/main/internal/signals/outcome.go)](https://github.com/kenn-io/agentsview/blob/main/internal/signals/outcome.go) within the `ClassifyOutcome` function.

### Score Signal

The **Score** signal produces a numeric quality rating from 0 to 100 that reflects prompt quality, cost efficiency, and tool-usage patterns. The algorithm is implemented in [[`internal/signals/score.go`](https://github.com/kenn-io/agentsview/blob/main/internal/signals/score.go)](https://github.com/kenn-io/agentsview/blob/main/internal/signals/score.go) via `ComputeScore`.

### ToolHealth Signal

**ToolHealth** monitors external AI tools (such as Codex, Claude, or Aider) by tracking successful versus failing calls and detecting repeated "give-up" patterns. This analysis lives in [[`internal/signals/toolhealth.go`](https://github.com/kenn-io/agentsview/blob/main/internal/signals/toolhealth.go)](https://github.com/kenn-io/agentsview/blob/main/internal/signals/toolhealth.go).

### Heuristics Signal

**Heuristics** provide supplemental boolean flags—including `IsAutomated`, `IsRepeatedPrompt`, and `HasToolCallPending`—that other signals consume to improve classification accuracy. These flags are computed first in [[`internal/signals/heuristics.go`](https://github.com/kenn-io/agentsview/blob/main/internal/signals/heuristics.go)](https://github.com/kenn-io/agentsview/blob/main/internal/signals/heuristics.go).

## How the Outcome Classification Algorithm Works

The most visible component of the agentsview signal classification system is the outcome decision tree. The `ClassifyOutcome` function in [`internal/signals/outcome.go`](https://github.com/kenn-io/agentsview/blob/main/internal/signals/outcome.go) evaluates sessions through an eight-step priority ladder:

1. **Automated sessions** (`IsAutomated == true`) → returns `unknown` with low confidence.
2. **Very short sessions** (exactly two messages ending with an assistant) → returns `completed` with medium confidence.
3. **Sessions with fewer than three messages** → returns `unknown` (low confidence).
4. **Recent activity** (last activity within the `RecencyWindow` of 10 minutes) → returns `unknown` (low confidence, `IsRecent = true`).
5. **User-ended sessions** (`EndedWithRole == "user"`) → returns `abandoned`; confidence upgrades to **high** once the session reaches at least 10 messages.
6. **Failure streak** (`FinalFailureStreak >= 3`) → returns `errored` (medium confidence).
7. **Assistant-ended sessions** (`EndedWithRole == "assistant"`) → returns `completed`; confidence drops to **low** if `hasGiveUpPattern` detects phrases like "I'm unable to..." in the final assistant message.
8. **Fallback** → returns `unknown` (low confidence).

Supporting helper functions include:

- `isRecent(t time.Time) bool` – validates the 10-minute recency window.
- `hasGiveUpPattern(text string) bool` – scans for canned phrases indicating model surrender.

The function returns an `OutcomeResult` struct containing `Outcome`, `Confidence`, and `IsRecent` fields, which the sync engine persists to the `sessions` table columns `outcome`, `outcome_confidence`, and `outcome_is_recent`.

## Signal Integration Architecture

All signals are **pure functions**—they accept a small input struct and return deterministic outputs without side effects. This design ensures consistent behavior across SQLite and PostgreSQL backends and enables comprehensive unit testing via [`outcome_test.go`](https://github.com/kenn-io/agentsview/blob/main/outcome_test.go) and [`score_test.go`](https://github.com/kenn-io/agentsview/blob/main/score_test.go).

The integration flow follows this sequence:

1. **[`internal/sync/engine.go`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/engine.go)** triggers when a new session is parsed or updated.
2. **Heuristics** compute first, providing boolean flags to downstream signals.
3. **Outcome**, **Score**, and **ToolHealth** execute in parallel using the heuristic results.
4. **[`internal/db/sessions.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/sessions.go)** persists the aggregated results to the database schema.
5. **REST API** (`/api/v1/sessions`) and the **Svelte UI** consume these signals to enable filtering by outcome, highlighting recent sessions, and sorting by quality score.

This architecture ensures that the agentsview signal classification system remains testable, database-agnostic, and safe to invoke during high-frequency sync operations.

## Code Examples

### Classifying a Session Outcome in Go

```go
import (
    "fmt"
    "time"
    "github.com/kenn-io/agentsview/internal/signals"
)

func exampleOutcome() {
    // Input normally derived from database queries.
    in := signals.OutcomeInput{
        IsAutomated:        false,
        MessageCount:       12,
        EndedWithRole:      "assistant",
        FinalFailureStreak: 0,
        LastAssistantText:  "All done! 🎉",
        LastActivity:       time.Now().Add(-15 * time.Minute),
    }

    // Pure classification without database access.
    out := signals.ClassifyOutcome(in)

    fmt.Printf("Outcome: %s (confidence %s, recent=%t)\n",
        out.Outcome, out.Confidence, out.IsRecent)
}

```

*Result*: `Outcome: completed (confidence medium, recent=false)`.

### Querying Signals via SQL

```sql
SELECT id, outcome, outcome_confidence
FROM sessions
WHERE outcome = 'abandoned' 
  AND outcome_confidence = 'high';

```

### Computing Quality Scores

```go
import "github.com/kenn-io/agentsview/internal/signals"

func exampleScore(sess *Session) {
    // ComputeScore accepts the raw parsed session data.
    score := signals.ComputeScore(sess)
    fmt.Println("Quality score:", score) // Integer 0-100.
}

```

## Summary

- The **agentsview signal classification system** uses pure-Go functions in `internal/signals/` to annotate sessions with machine-readable metadata.
- **Four core signals**—Outcome, Score, ToolHealth, and Heuristics—provide complete session intelligence without manual intervention.
- **Outcome classification** follows an eight-step decision tree prioritizing automation status, message count, recency, and failure patterns.
- **Pure function architecture** ensures deterministic results across SQLite and PostgreSQL while enabling isolated unit testing.
- Signals are computed during sync by [`internal/sync/engine.go`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/engine.go) and exposed via the REST API for UI filtering and analytics.

## Frequently Asked Questions

### How does Agentsview determine if a session is "recent"?

The system checks if the session's `LastActivity` timestamp falls within the `RecencyWindow` constant of 10 minutes. The `isRecent` helper function in [`internal/signals/outcome.go`](https://github.com/kenn-io/agentsview/blob/main/internal/signals/outcome.go) performs this calculation, setting `IsRecent = true` when the threshold is met and assigning low confidence to the outcome classification.

### Can the signal classification logic be customized or extended?

Yes. Because the agentsview signal classification system uses pure functions without database dependencies, developers can fork the `internal/signals/` package and modify the decision trees in [`outcome.go`](https://github.com/kenn-io/agentsview/blob/main/outcome.go) or adjust the scoring weights in [`score.go`](https://github.com/kenn-io/agentsview/blob/main/score.go). The sync engine automatically picks up these changes during the next session processing cycle.

### What happens when a session ends with a "give-up" pattern?

If `EndedWithRole` equals `"assistant"` and the `hasGiveUpPattern` function detects phrases like "I'm unable to" in the final message, the outcome is classified as `completed` but with **low** confidence rather than medium. This prevents false positives where the model technically responded but failed to solve the user's request.

### Why does the system mark automated sessions as "unknown"?

Automated sessions (where `IsAutomated == true` per [`internal/signals/heuristics.go`](https://github.com/kenn-io/agentsview/blob/main/internal/signals/heuristics.go)) are intentionally excluded from standard outcome classification because they typically represent scripted workflows rather than organic user interactions. This prevents skewing analytics and ensures that metrics like abandonment rates reflect actual user behavior.