@hybridlabor-api/bdb-synapse 1.0.0

package/internal/model/agent.go

@@ -0,0 +1,63 @@
+package model
+
+const AgentGraphVersion = 1
+
+const (
+	AgentKindMain     = "main"
+	AgentKindSubagent = "subagent"
+
+	AgentStatusMain     = "main"
+	AgentStatusLaunched = "launched"
+	AgentStatusFailed   = "failed"
+	AgentStatusUnknown  = "unknown"
+
+	TraceAvailabilityAvailable   = "available"
+	TraceAvailabilityMissing     = "missing"
+	TraceAvailabilityUnavailable = "unavailable"
+
+	AgentLinkQualityExact       = "exact"
+	AgentLinkQualityDerived     = "derived"
+	AgentLinkQualityUnavailable = "unavailable"
+
+	AgentLinkMethodRoot                     = "root"
+	AgentLinkMethodCodexAgentID             = "codex-agent-id"
+	AgentLinkMethodCodexParentThreadID      = "codex-parent-thread-id"
+	AgentLinkMethodClaudeToolUseID          = "claude-tool-use-id"
+	AgentLinkMethodClaudeSubagentsDirectory = "claude-subagents-directory"
+	AgentLinkMethodUnavailable              = "unavailable"
+)
+
+type AgentGraph struct {
+	Version        int         `json:"version"`
+	RootSessionKey string      `json:"rootSessionKey"`
+	Agents         []AgentNode `json:"agents"`
+}
+
+type AgentNode struct {
+	ID                 string `json:"id"`
+	ParentID           string `json:"parentId,omitempty"`
+	Depth              int    `json:"depth"`
+	Kind               string `json:"kind"`
+	Label              string `json:"label"`
+	Role               string `json:"role,omitempty"`
+	InstructionPreview string `json:"instructionPreview,omitempty"`
+	LaunchSeq          *int   `json:"launchSeq,omitempty"`
+	LaunchCallID       string `json:"launchCallId,omitempty"`
+	Status             string `json:"status"`
+	TraceAvailability  string `json:"traceAvailability"`
+	TraceSessionKey    string `json:"traceSessionKey,omitempty"`
+	TraceEventCount    int    `json:"traceEventCount"`
+	LinkQuality        string `json:"linkQuality"`
+	LinkMethod         string `json:"linkMethod"`
+}
+
+type AgentSessionMeta struct {
+	SourceID        string
+	RootSessionID   string
+	ParentSessionID string
+	AgentPath       string
+	Depth           int
+	Label           string
+	Role            string
+	LaunchCallID    string
+}

package/internal/model/agent_schema_test.go

@@ -0,0 +1,86 @@
+package model
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/santhosh-tekuri/jsonschema/v6"
+)
+
+func TestAgentGraphSchemaAcceptsRepresentativeGraph(t *testing.T) {
+	launchSeq := 2
+	graph := AgentGraph{
+		Version:        AgentGraphVersion,
+		RootSessionKey: "root-key",
+		Agents: []AgentNode{
+			{
+				ID:                "agt_main",
+				Kind:              AgentKindMain,
+				Label:             "Main",
+				Status:            AgentStatusMain,
+				TraceAvailability: TraceAvailabilityAvailable,
+				TraceSessionKey:   "root-key",
+				TraceEventCount:   12,
+				LinkQuality:       AgentLinkQualityExact,
+				LinkMethod:        AgentLinkMethodRoot,
+			},
+			{
+				ID:                 "agt_child",
+				ParentID:           "agt_main",
+				Depth:              1,
+				Kind:               AgentKindSubagent,
+				Label:              "Reviewer",
+				Role:               "reviewer",
+				InstructionPreview: "Review the change",
+				LaunchSeq:          &launchSeq,
+				LaunchCallID:       "call-review",
+				Status:             AgentStatusLaunched,
+				TraceAvailability:  TraceAvailabilityAvailable,
+				TraceSessionKey:    "child-key",
+				TraceEventCount:    3,
+				LinkQuality:        AgentLinkQualityExact,
+				LinkMethod:         AgentLinkMethodCodexAgentID,
+			},
+			{
+				ID:                "agt_missing",
+				ParentID:          "agt_main",
+				Depth:             1,
+				Kind:              AgentKindSubagent,
+				Label:             "Missing",
+				Status:            AgentStatusLaunched,
+				TraceAvailability: TraceAvailabilityMissing,
+				LinkQuality:       AgentLinkQualityDerived,
+				LinkMethod:        AgentLinkMethodClaudeSubagentsDirectory,
+			},
+			{
+				ID:                "agt_failed",
+				ParentID:          "agt_main",
+				Depth:             1,
+				Kind:              AgentKindSubagent,
+				Label:             "Failed",
+				Status:            AgentStatusFailed,
+				TraceAvailability: TraceAvailabilityUnavailable,
+				LinkQuality:       AgentLinkQualityUnavailable,
+				LinkMethod:        AgentLinkMethodUnavailable,
+			},
+		},
+	}
+
+	document, err := json.Marshal(graph)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var value any
+	if err := json.Unmarshal(document, &value); err != nil {
+		t.Fatal(err)
+	}
+
+	compiler := jsonschema.NewCompiler()
+	schema, err := compiler.Compile("../../schema/agent-graph.schema.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := schema.Validate(value); err != nil {
+		t.Fatalf("representative AgentGraph violates schema: %v\n%s", err, document)
+	}
+}

package/internal/model/agent_test.go

@@ -0,0 +1,64 @@
+package model
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestAgentNodeOmitsMainRelationshipFields(t *testing.T) {
+	node := AgentNode{
+		ID:                "main",
+		Depth:             0,
+		Kind:              AgentKindMain,
+		Label:             "Main",
+		Status:            AgentStatusMain,
+		TraceAvailability: TraceAvailabilityAvailable,
+		TraceSessionKey:   "root-key",
+		TraceEventCount:   12,
+		LinkQuality:       AgentLinkQualityExact,
+		LinkMethod:        AgentLinkMethodRoot,
+	}
+
+	data, err := json.Marshal(node)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got map[string]any
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatal(err)
+	}
+	if _, ok := got["parentId"]; ok {
+		t.Fatalf("main node serialized parentId: %s", data)
+	}
+	if _, ok := got["launchSeq"]; ok {
+		t.Fatalf("main node serialized launchSeq: %s", data)
+	}
+}
+
+func TestAgentNodeSerializesZeroLaunchSeq(t *testing.T) {
+	zero := 0
+	node := AgentNode{
+		ID:                "child",
+		ParentID:          "main",
+		Depth:             1,
+		Kind:              AgentKindSubagent,
+		Label:             "Child",
+		LaunchSeq:         &zero,
+		Status:            AgentStatusLaunched,
+		TraceAvailability: TraceAvailabilityMissing,
+		LinkQuality:       AgentLinkQualityExact,
+		LinkMethod:        AgentLinkMethodCodexAgentID,
+	}
+
+	data, err := json.Marshal(node)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got map[string]any
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatal(err)
+	}
+	if got["launchSeq"] != float64(0) {
+		t.Fatalf("launchSeq = %#v, JSON = %s", got["launchSeq"], data)
+	}
+}

package/internal/model/model.go

@@ -0,0 +1,175 @@
+package model
+
+type Rect struct {
+	X float64 `json:"x"`
+	Z float64 `json:"z"`
+	W float64 `json:"w"`
+	D float64 `json:"d"`
+}
+
+type RepoMeta struct {
+	Root        string `json:"root"`
+	Commit      string `json:"commit,omitempty"`
+	Dirty       bool   `json:"dirty"`
+	GeneratedAt string `json:"generatedAt"`
+	// Truncated marks a map that hit a scan or size budget — the session's
+	// tree (or its trace targets) holds more than the citymap shows.
+	Truncated bool `json:"truncated,omitempty"`
+}
+
+type CityMap struct {
+	Version int        `json:"version"`
+	Repo    RepoMeta   `json:"repo"`
+	Files   []CityFile `json:"files"`
+	Dirs    []CityDir  `json:"dirs"`
+	Layout  LayoutMeta `json:"layout"`
+}
+
+type CityFile struct {
+	ID    int    `json:"id"`
+	Path  string `json:"path"`
+	Dir   string `json:"dir"`
+	Lines int    `json:"lines"`
+	Bytes int64  `json:"bytes"`
+	Lang  string `json:"lang,omitempty"`
+	Rect  Rect   `json:"rect"`
+	Ghost bool   `json:"ghost"`
+}
+
+type CityDir struct {
+	Path      string `json:"path"`
+	Depth     int    `json:"depth"`
+	Rect      Rect   `json:"rect"`
+	FileCount int    `json:"fileCount"`
+	Lines     int    `json:"lines"`
+}
+
+type LayoutMeta struct {
+	Algorithm string `json:"algorithm"`
+	Weight    string `json:"weight"`
+}
+
+type Trace struct {
+	Version int          `json:"version"`
+	Session TraceSession `json:"session"`
+	Events  []Event      `json:"events"`
+	Marks   []Mark       `json:"marks"`
+	Stats   Stats        `json:"stats"`
+}
+
+type TraceSession struct {
+	ID         string `json:"id"`
+	Harness    string `json:"harness"`
+	Model      string `json:"model,omitempty"`
+	Title      string `json:"title,omitempty"`
+	Cwd        string `json:"cwd,omitempty"`
+	Commit     string `json:"commit,omitempty"`
+	StartedAt  string `json:"startedAt,omitempty"`
+	EndedAt    string `json:"endedAt,omitempty"`
+	EventCount int    `json:"eventCount"`
+	Path       string `json:"path,omitempty"`
+}
+
+type Event struct {
+	Seq         int            `json:"seq"`
+	Timestamp   string         `json:"ts,omitempty"`
+	Tool        string         `json:"tool"`
+	Action      string         `json:"action"`
+	Targets     []Target       `json:"targets"`
+	Outside     []OutsideTouch `json:"outside,omitempty"`
+	ResultBytes int            `json:"resultBytes"`
+	IsError     bool           `json:"isError"`
+	// OutcomeKnown distinguishes a recorded success from an unknown non-error
+	// result. IsError remains sufficient to identify failures in older traces.
+	OutcomeKnown bool   `json:"outcomeKnown,omitempty"`
+	Summary      string `json:"summary"`
+}
+
+type Target struct {
+	Path   string   `json:"path"`
+	FileID *int     `json:"fileId,omitempty"`
+	Touch  string   `json:"touch"`
+	Lines  [][2]int `json:"lines,omitempty"`
+	Weak   bool     `json:"weak,omitempty"`
+}
+
+type OutsideTouch struct {
+	Scope string `json:"scope"`
+	Path  string `json:"path"`
+}
+
+type Mark struct {
+	Seq  int    `json:"seq"`
+	Type string `json:"type"`
+	Note string `json:"note,omitempty"`
+}
+
+type Stats struct {
+	FilesInRepo           int          `json:"filesInRepo"`
+	Fovea                 int          `json:"fovea"`
+	Parafovea             int          `json:"parafovea"`
+	Edited                int          `json:"edited"`
+	EventsBeforeFirstEdit int          `json:"eventsBeforeFirstEdit"`
+	RegressionRate        float64      `json:"regressionRate"`
+	ErrorRate             float64      `json:"errorRate"`
+	Actions               ActionCounts `json:"actions"`
+	Errors                ActionCounts `json:"errors"`
+	MaxEditsPerFile       int          `json:"maxEditsPerFile"`
+	// ChurnFiles counts files edited in three or more events.
+	ChurnFiles  int   `json:"churnFiles"`
+	UserTurns   int   `json:"userTurns"`
+	Compactions int   `json:"compactions"`
+	Subagents   int   `json:"subagents"`
+	ResultBytes int64 `json:"resultBytes"`
+	// EditsAfterLastVerify counts edit events after the last verify event;
+	// when the session never ran a verify it counts every edit event.
+	EditsAfterLastVerify int `json:"editsAfterLastVerify"`
+	// Observability grades each derived metric's source signal so the UI can
+	// tell a true zero from a blind spot in the session log.
+	Observability Observability `json:"observability"`
+}
+
+// Observability values: "exact" when the harness records the signal
+// structurally, "estimated" when it is inferred from command or output text,
+// "unavailable" when the log carries no usable signal.
+const (
+	ObservabilityExact       = "exact"
+	ObservabilityEstimated   = "estimated"
+	ObservabilityUnavailable = "unavailable"
+)
+
+type Observability struct {
+	Reads  string `json:"reads"`
+	Errors string `json:"errors"`
+}
+
+// ActionCounts tallies events per action class; as Stats.Errors it tallies
+// only the events that returned an error.
+type ActionCounts struct {
+	Search int `json:"search"`
+	Read   int `json:"read"`
+	Edit   int `json:"edit"`
+	Exec   int `json:"exec"`
+	Verify int `json:"verify"`
+	Other  int `json:"other"`
+}
+
+type SessionMeta struct {
+	Key       string `json:"key"`
+	ID        string `json:"id"`
+	Harness   string `json:"harness"`
+	Title     string `json:"title,omitempty"`
+	Path      string `json:"path"`
+	Cwd       string `json:"cwd,omitempty"`
+	Model     string `json:"model,omitempty"`
+	GitBranch string `json:"gitBranch,omitempty"`
+	StartedAt string `json:"startedAt,omitempty"`
+	EndedAt   string `json:"endedAt,omitempty"`
+	// EventCount and UserTurns together are the cheap staleness signal for
+	// report badges: user messages land on marks, not events, so the count
+	// alone misses exactly the follow-ups that matter most.
+	EventCount int               `json:"eventCount"`
+	UserTurns  int               `json:"userTurns"`
+	Auxiliary  bool              `json:"-"`
+	Agent      *AgentSessionMeta `json:"-"`
+}

package/internal/model/report.go

@@ -0,0 +1,166 @@
+package model
+
+// Report is the third first-class artifact next to CityMap and Trace: an
+// LLM-assisted evaluation of one session trace. The LLM contributes findings
+// and narrative; dimension verdicts are always derived mechanically from
+// finding severities so two reports stay comparable.
+type Report struct {
+	Version        int               `json:"version"`
+	Session        ReportSession     `json:"session"`
+	Judge          ReportJudge       `json:"judge"`
+	TaskSummary    string            `json:"taskSummary"`
+	Dimensions     []ReportDimension `json:"dimensions"`
+	Rubric         *Rubric           `json:"rubric,omitempty"`
+	NotableMoments []ReportMoment    `json:"notableMoments,omitempty"`
+	Narrative      string            `json:"narrative"`
+}
+
+// ReportSession pins the report to the trace state it was generated from;
+// EventCount is a cheap display/badge signal — freshness is decided by
+// ReportJudge.InputDigest, which also sees user messages and event content.
+type ReportSession struct {
+	ID         string `json:"id"`
+	Harness    string `json:"harness"`
+	Model      string `json:"model,omitempty"`
+	EventCount int    `json:"eventCount"`
+	// UserTurns mirrors SessionMeta.UserTurns at generation time, giving the
+	// badge's cheap staleness check eyes on message-only session growth.
+	UserTurns int `json:"userTurns,omitempty"`
+}
+
+type ReportJudge struct {
+	CLI string `json:"cli"`
+	// Model names the LLM that actually judged (best-effort, reported by the
+	// CLI itself); display and comparability only — never part of freshness.
+	Model string `json:"model,omitempty"`
+	// RequestedModel keeps the alias the run was asked for (e.g. "sonnet"),
+	// so a repeated aliased request can recognize its own cached report.
+	RequestedModel string `json:"requestedModel,omitempty"`
+	PromptVersion  int    `json:"promptVersion"`
+	// RubricPromptVersion is set only when the report carries a scored rubric;
+	// deterministic skips (no/weak task text) stay fresh across rubric prompt
+	// revisions because no generation happened.
+	RubricPromptVersion int    `json:"rubricPromptVersion,omitempty"`
+	GeneratedAt         string `json:"generatedAt"`
+	// InputDigest fingerprints the exact evidence document the judge read;
+	// the report is fresh only while the trace still renders to this digest.
+	InputDigest string `json:"inputDigest,omitempty"`
+}
+
+// Dimension names, fixed set.
+const (
+	DimensionExploration  = "exploration"
+	DimensionScope        = "scope"
+	DimensionWandering    = "wandering"
+	DimensionVerification = "verification"
+)
+
+// DimensionNames lists the four evaluation dimensions in display order.
+var DimensionNames = []string{DimensionExploration, DimensionScope, DimensionWandering, DimensionVerification}
+
+// Verdict values; SeverityInfo maps to VerdictGood.
+const (
+	VerdictGood             = "good"
+	VerdictWarning          = "warning"
+	VerdictProblem          = "problem"
+	VerdictInsufficientData = "insufficient-data"
+)
+
+const (
+	SeverityInfo    = "info"
+	SeverityWarning = "warning"
+	SeverityProblem = "problem"
+)
+
+type ReportDimension struct {
+	Name     string          `json:"name"`
+	Verdict  string          `json:"verdict"`
+	Findings []ReportFinding `json:"findings"`
+}
+
+type ReportFinding struct {
+	Claim    string `json:"claim"`
+	Severity string `json:"severity"`
+	// Always at least one entry — evidence-less findings are dropped at
+	// parse time, and the schema marks the field required accordingly.
+	EvidenceSeqs []int `json:"evidenceSeqs"`
+}
+
+type ReportMoment struct {
+	Seq  int    `json:"seq"`
+	Note string `json:"note"`
+}
+
+// Rubric statuses and skip/degrade reasons.
+const (
+	RubricStatusScored      = "scored"
+	RubricStatusUnavailable = "unavailable"
+
+	RubricReasonGenerationFailed = "generation-failed"
+	RubricReasonNoTaskText       = "no-task-text"
+	RubricReasonWeakTaskText     = "weak-task-text"
+	// RubricReasonNoEvents skips traces with no tool events: with nothing to
+	// cite, every finding would be dropped and criteria would default to
+	// good verdicts on zero evidence.
+	RubricReasonNoEvents = "no-events"
+)
+
+// Rubric generation input modes. A rubric generated with the full evidence
+// document may absorb this attempt's implementation choices into its anchors;
+// comparison across agents must only ever reuse task-sourced rubrics.
+const (
+	RubricSourceFull = "full"
+	RubricSourceTask = "task"
+)
+
+// Criterion evidence coverage. Unlike severities these never feed warnings:
+// a criterion the log cannot evidence rolls up to insufficient-data instead
+// of counting against the agent.
+const (
+	CoverageSufficient = "sufficient"
+	CoveragePartial    = "partial"
+	CoverageNone       = "none"
+)
+
+// Rubric is the task-accounting layer of a report: session-specific criteria
+// generated before scoring, grouped by the independent tasks the judge
+// enumerated from the user's messages. The fixed dimensions never depend on
+// it — a rubric failure degrades to a dimensions-only report.
+type Rubric struct {
+	Status string `json:"status"`
+	// Reason qualifies an unavailable rubric: generation-failed after retry,
+	// or a deterministic skip (no-task-text, weak-task-text).
+	Reason string `json:"reason,omitempty"`
+	Source string `json:"source,omitempty"`
+	// TaskDigest fingerprints the task wording the rubric was derived from;
+	// a re-evaluation whose digest still matches reuses the rubric unchanged.
+	TaskDigest string       `json:"taskDigest,omitempty"`
+	Tasks      []RubricTask `json:"tasks,omitempty"`
+	// Note carries what the scorer felt the rubric did not let it express.
+	Note string `json:"note,omitempty"`
+}
+
+type RubricTask struct {
+	Title string `json:"title"`
+	Type  string `json:"type,omitempty"`
+	// AnchorUserMessages are [user #N] ordinals from the evidence document,
+	// validated against the ordinals actually rendered there.
+	AnchorUserMessages []int `json:"anchorUserMessages"`
+	// AnchorSeqs are the mark seqs those ordinals resolve to — derived in Go,
+	// never taken from the judge — so the UI can jump to a task's start.
+	AnchorSeqs []int             `json:"anchorSeqs,omitempty"`
+	Criteria   []RubricCriterion `json:"criteria"`
+}
+
+type RubricCriterion struct {
+	ID    string `json:"id"`
+	Title string `json:"title"`
+	Why   string `json:"why,omitempty"`
+	Good  string `json:"good,omitempty"`
+	Bad   string `json:"bad,omitempty"`
+	// Coverage and findings come from the scoring pass; verdict is rolled up
+	// mechanically (coverage none forces insufficient-data).
+	Coverage string          `json:"coverage,omitempty"`
+	Verdict  string          `json:"verdict"`
+	Findings []ReportFinding `json:"findings"`
+}