@hybridlabor-api/bdb-synapse 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricko Yu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+# <img src="assets/logo.svg" alt="" width="30" /> BDB Synapse
+
+A visualization tool that replays coding-agent sessions on a 3D map of your codebase.
+
+**BDB Synapse** is an extended fork of the excellent [cosmtrek/mindwalk](https://github.com/cosmtrek/mindwalk) (MIT License), created to support the BDB ecosystem of agents. It adds support for the Antigravity (agy) CLI alongside the existing supported agents.
+
+## The problem
+
+A session log records what an agent did, but not how it understood the task:
+which parts of the repo it treated as relevant, where it explored before it
+acted, whether its footprint matched the scope you had in mind. Reading the
+raw JSONL line by line doesn't answer any of that.
+
+## The idea
+
+Draw the repository as a night map, and play the session back as light moving
+through it: where the agent searched, read, and edited, the map glows —
+everything else stays dark. The agent's understanding of the task becomes a
+shape you can see at a glance. One Go binary reads Claude Code, Codex, pi, and Antigravity (agy)
+session logs, fully local; viewing sends nothing anywhere. The one exception
+is the optional session evaluation: when you explicitly run it, a summary of
+that session (task wording, file paths, event digests) is sent to the model
+behind your own `claude` or `codex` CLI — see
+[Session evaluation](#session-evaluation).
+
+## Quick start
+
+To build from source: `make setup && make build` → `bin/synapse`.
+
+With no arguments, Synapse scans `~/.claude/projects`, `~/.codex/sessions`,
+`~/.pi/agent/sessions`, and `~/.gemini/antigravity-cli/brain`, serves the UI on a random local port, and opens a
+browser:
+
+```text
+synapse serve [--port N] [--no-open] [--claude-dir DIR] [--codex-dir DIR] [--pi-dir DIR] [--agy-dir DIR]
+synapse open [--no-open] <session.jsonl>   open one specific session
+synapse map [--no-open] <repo>             open a repository map, no session needed
+synapse build <repo> [-o out]              write the repository citymap JSON
+synapse trace <session> [-o out]           write the normalized trace JSON
+synapse analyze <session> [--judge claude|codex] [--model name] [--no-rubric]
+                                            evaluate one session (see below)
+```
+
+## Reading the picture
+
+- **Tree / Terrain views** — the repo as a radial tree or a treemap plain;
+  glow ∝ how deeply and how often a file was touched.
+- **Touch states** — each file keeps its deepest touch: seen (moss green),
+  read (moonlight blue), edited (warm amber), unvisited (dark). Files the
+  session touched that are no longer in the repo linger as wireframe ghosts.
+  The HUD folds friction signals — error rate, churned files, edits after the
+  last verify — into a review strip.
+- **Playback deck** — scrub or play the session over a bucketed histogram of
+  the run. Bars sit on a cool/warm spectrum: observation stays cool (search,
+  read, exec), mutation glows warm (edit, verify), so editing phases jump out
+  at a glance. Restart, speed, and video export fold into the deck's `⋯` menu;
+  export records the playback to a `.webm` entirely client-side.
+- **Timeline marks** — `◇` context compactions, `○` subagent launches,
+  `›` user turns; every mark is a click-to-jump target.
+- **Agent lenses** — when a session launched subagents, the HUD carries a
+  subagent count and an agents panel: pick a lens to replay any subagent's
+  trace on the same map, then step back out to the main trace.
+- **Inspector** — click a file to pin its visit history; click a visit row to
+  jump the playhead to that moment.
+- **Evaluate** — ask a local agent CLI to judge the session's trajectory,
+  scored against criteria drafted from your own request; session rows carry
+  the evaluation state as a quiet badge. See
+  [Session evaluation](#session-evaluation).
+- **Repo map** — `mindwalk map <repo>` (or the folder icon in the session
+  rail) renders any repository's citymap with no session attached; height
+  encodes lines of code instead of attention.
+
+![the same session on the terrain view](assets/screenshot-terrain.png)
+
+![agent lenses over the same session](assets/screenshot-agents.png)
+
+Keyboard: `Space` play/pause · `←`/`→` step (`⇧` ×10) · `Home`/`End` ends ·
+`S` speed · `V` view · `E` next edit · `X` next error · `M` next mark ·
+`⌘B` session rail.
+
+## Session evaluation
+
+The evaluate panel (and `mindwalk analyze`) asks a local agent CLI to judge
+how the session went. A report has two layers:
+
+- **Process dimensions** — exploration, scope, wandering, verification: four
+  fixed lenses, the same for every session, so reports stay comparable.
+- **Task scorecard** — before scoring, the judge drafts criteria from your
+  own request wording: what would count as done for *this* task, grouped per
+  task when the session carried several. Each criterion is then scored
+  against the session, alongside the dimensions, in one pass.
+
+Every finding in either layer must cite timeline events you can click
+through to, and no verdict is the model's to decide: dimension and criterion
+verdicts are rolled up mechanically from finding severities. When the log
+simply can't show whether a criterion was met, its coverage drops and the
+verdict reads "no signal" — an unverifiable criterion is a blind spot, not a
+failure. Pick the judge (any installed CLI) and its model in the panel; the
+report records who actually judged.
+
+The scorecard steps aside rather than getting in the way: sessions with no
+tool events or too little task text skip it, and a failed criteria draft
+degrades to a dimensions-only report. `--no-rubric` (or `"rubric": false` on
+the analyze API) skips it explicitly, in a single judge call. How the
+scorecard is built — and why it is shaped the way it is — is covered in
+[docs/dynamic-rubric-evaluation.md](docs/dynamic-rubric-evaluation.md).
+
+**What leaves your machine, and only when you ask:** evaluation runs your own
+`claude` or `codex` CLI — up to two sealed calls, one drafting criteria and
+one scoring. Both send only that session's summary — the user messages'
+wording, file paths, and one-line event digests — to the model behind your
+account. Nothing is sent while viewing sessions, and no other session is
+included. The judge subprocess runs sealed: no tools, no MCP servers, no user
+or project settings, and no session persistence.
+
+Reports are cached in `~/.mindwalk/reports`, one per session; a report goes
+stale (never auto-reruns) when the session's content changes. Re-evaluating
+a session whose task wording hasn't changed reuses the drafted criteria —
+scores can move, the yardstick doesn't.
+
+## Under the hood
+
+Three artifacts, kept deliberately separate:
+
+1. a **trace** — the session log normalized into an ordered stream of
+   file-touch events (`internal/adapter`, one adapter per agent format);
+   adapters also correlate subagent sessions into an agent graph, so each
+   subagent's trace can be replayed on its own;
+2. a **citymap** — a deterministic layout of the repository
+   (`internal/citymap`); the same tree always produces the same map, so
+   replays are comparable across sessions;
+3. a **report** — an LLM judge's evidence-anchored findings about one
+   session (`internal/judge`): four fixed process dimensions plus a
+   task-specific scorecard; the judge only contributes findings, verdicts
+   are always rolled up mechanically, so reports stay comparable too.
+
+A local Go server (`internal/server`) joins them and serves the
+React/Three.js frontend (`web`). `schema/` mirrors the exported JSON contracts.
+
+## Contributing
+
+Issues and pull requests are welcome. To get a working dev setup:
+
+```sh
+make setup   # install frontend dependencies
+make serve   # dev server on :8765, serving web/dist from the working tree
+make test    # go test + frontend build — run before sending a PR
+make build   # regenerate embedded assets and bin/mindwalk
+```
+
+Ground rules (see [AGENTS.md](AGENTS.md) for the full architecture notes):
+
+- Keep the boundaries: adapters don't know about rendering, citymap generation
+  doesn't depend on playback, the judge reads only the normalized trace, and
+  the server just connects the pieces.
+- Keep Go code `gofmt`-ed; never hand-edit `internal/server/static` —
+  regenerate it with `make build`.
+- When trace, citymap, or report JSON shapes change, update `schema/` and the
+  relevant tests in the same change.
+
+## Star History
+
+<a href="https://www.star-history.com/?repos=cosmtrek%2Fmindwalk&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=cosmtrek/mindwalk&type=date&theme=dark&legend=top-left&sealed_token=6ylPq85HVVSbxQtqpYdSNx2EFZXMTk4AhnMG197AQm7TDwfenvf415jqPnPRxRiXz4l_f7NRUM2OlNDptSLXC18Q7cX8CQpUBkJtepMUJg6gYhdNM9fTBqBN08fY19HNfmoCFjN2SThT9w81tO_WWCThVBZtf8tMRUC7Bmi3jJ3HFs-4734aDGFw-LOe" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=cosmtrek/mindwalk&type=date&legend=top-left&sealed_token=6ylPq85HVVSbxQtqpYdSNx2EFZXMTk4AhnMG197AQm7TDwfenvf415jqPnPRxRiXz4l_f7NRUM2OlNDptSLXC18Q7cX8CQpUBkJtepMUJg6gYhdNM9fTBqBN08fY19HNfmoCFjN2SThT9w81tO_WWCThVBZtf8tMRUC7Bmi3jJ3HFs-4734aDGFw-LOe" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=cosmtrek/mindwalk&type=date&legend=top-left&sealed_token=6ylPq85HVVSbxQtqpYdSNx2EFZXMTk4AhnMG197AQm7TDwfenvf415jqPnPRxRiXz4l_f7NRUM2OlNDptSLXC18Q7cX8CQpUBkJtepMUJg6gYhdNM9fTBqBN08fY19HNfmoCFjN2SThT9w81tO_WWCThVBZtf8tMRUC7Bmi3jJ3HFs-4734aDGFw-LOe" />
+ </picture>
+</a>
+
+## License
+
+[MIT](LICENSE) © 2026 Ricko Yu

package/cmd/rubriceval/main.go

@@ -0,0 +1,308 @@
+// rubriceval is the offline evaluation bench for the rubric judge pipeline
+// (design doc §15, M1.5). It drives the real judge.Analyze over a batch of
+// historical sessions and reports the gate metrics: rubric outcome rates,
+// coverage-sufficient rate, dead-criteria rate, and per-phase latency.
+//
+// Usage:
+//
+//	go run ./cmd/rubriceval -o OUTDIR [-cli codex] [-workers 3] <session.jsonl>...
+//
+// Every session costs real judge-CLI calls; this is a bench, not a test.
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/hybridlabor-api/bdb-synapse/internal/adapter"
+	"github.com/hybridlabor-api/bdb-synapse/internal/adapter/claudecode"
+	"github.com/hybridlabor-api/bdb-synapse/internal/adapter/codex"
+	"github.com/hybridlabor-api/bdb-synapse/internal/judge"
+	"github.com/hybridlabor-api/bdb-synapse/internal/model"
+)
+
+// timingRunner wraps the real CLI runner and records each sealed call. The
+// prompt text distinguishes the phases: the generation prompt announces
+// itself, and the unified scoring prompt names the RUBRIC input section.
+type timingRunner struct {
+	inner judge.Runner
+	// dumpDir, when set, saves every call's raw output for failure analysis.
+	dumpDir string
+	session string
+	mu      sync.Mutex
+	calls   []callRecord
+}
+
+type callRecord struct {
+	Kind        string  `json:"kind"` // rubric | scoring-unified | scoring-legacy
+	DurationSec float64 `json:"durationSec"`
+	InputBytes  int     `json:"inputBytes"`
+	OutputBytes int     `json:"outputBytes"`
+}
+
+func (t *timingRunner) Run(ctx context.Context, prompt, input string) (judge.RunResult, error) {
+	start := time.Now()
+	result, err := t.inner.Run(ctx, prompt, input)
+	kind := "scoring-legacy"
+	switch {
+	case strings.Contains(prompt, "designing an evaluation rubric"):
+		kind = "rubric"
+	case strings.Contains(prompt, "RUBRIC"):
+		kind = "scoring-unified"
+	}
+	t.mu.Lock()
+	t.calls = append(t.calls, callRecord{
+		Kind:        kind,
+		DurationSec: time.Since(start).Seconds(),
+		InputBytes:  len(input),
+		OutputBytes: len(result.Text),
+	})
+	call := len(t.calls)
+	t.mu.Unlock()
+	if t.dumpDir != "" {
+		name := fmt.Sprintf("%s.call%d.%s.txt", t.session, call, kind)
+		_ = os.WriteFile(filepath.Join(t.dumpDir, name), []byte(result.Text), 0o644)
+	}
+	return result, err
+}
+
+func (t *timingRunner) Name() string { return t.inner.Name() }
+
+// sessionResult is one bench row; failures carry Error and nothing else.
+type sessionResult struct {
+	Session    string         `json:"session"`
+	Harness    string         `json:"harness,omitempty"`
+	Events     int            `json:"events,omitempty"`
+	TaskRunes  int            `json:"taskRunes"`
+	Status     string         `json:"status"` // scored | unavailable | no-rubric-layer | error
+	Reason     string         `json:"reason,omitempty"`
+	Tasks      int            `json:"tasks,omitempty"`
+	Criteria   int            `json:"criteria,omitempty"`
+	Sufficient int            `json:"sufficient,omitempty"`
+	Partial    int            `json:"partial,omitempty"`
+	None       int            `json:"none,omitempty"`
+	Dead       int            `json:"dead,omitempty"` // criteria with zero findings
+	Verdicts   map[string]int `json:"verdicts,omitempty"`
+	Calls      []callRecord   `json:"calls,omitempty"`
+	TotalSec   float64        `json:"totalSec"`
+	Error      string         `json:"error,omitempty"`
+}
+
+func main() {
+	outDir := flag.String("o", "", "output directory (required)")
+	cliName := flag.String("cli", "codex", "judge CLI")
+	modelName := flag.String("model", "", "judge model override")
+	workers := flag.Int("workers", 3, "concurrent sessions")
+	dumpRaw := flag.Bool("dump-raw", false, "save every judge call's raw output next to the reports")
+	flag.Parse()
+	if *outDir == "" || flag.NArg() == 0 {
+		fmt.Fprintln(os.Stderr, "usage: rubriceval -o OUTDIR [-cli codex] [-workers N] <session.jsonl>...")
+		os.Exit(2)
+	}
+	if err := os.MkdirAll(*outDir, 0o755); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+
+	sem := make(chan struct{}, *workers)
+	var wg sync.WaitGroup
+	var mu sync.Mutex
+	var results []sessionResult
+	for _, path := range flag.Args() {
+		wg.Add(1)
+		go func(path string) {
+			defer wg.Done()
+			sem <- struct{}{}
+			defer func() { <-sem }()
+			result := evalSession(path, *cliName, *modelName, *outDir, *dumpRaw)
+			mu.Lock()
+			results = append(results, result)
+			done := len(results)
+			mu.Unlock()
+			fmt.Printf("[%d/%d] %s → %s%s (%.0fs)\n", done, flag.NArg(), filepath.Base(path),
+				result.Status, reasonSuffix(result), result.TotalSec)
+		}(path)
+	}
+	wg.Wait()
+
+	sort.Slice(results, func(i, j int) bool { return results[i].Session < results[j].Session })
+	writeJSON(filepath.Join(*outDir, "results.json"), results)
+	printSummary(results)
+}
+
+func reasonSuffix(r sessionResult) string {
+	if r.Reason == "" {
+		return ""
+	}
+	return "/" + r.Reason
+}
+
+func evalSession(path, cliName, modelName, outDir string, dumpRaw bool) sessionResult {
+	result := sessionResult{Session: filepath.Base(path)}
+	trace, err := parseTrace(path)
+	if err != nil {
+		result.Status = "error"
+		result.Error = err.Error()
+		return result
+	}
+	result.Harness = trace.Session.Harness
+	result.Events = trace.Session.EventCount
+	result.TaskRunes = taskRunes(trace)
+
+	runner := &timingRunner{inner: judge.CLIRunner{CLI: cliName, Model: modelName}, session: strings.TrimSuffix(result.Session, ".jsonl")}
+	if dumpRaw {
+		runner.dumpDir = outDir
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), judge.DefaultTimeout)
+	defer cancel()
+	start := time.Now()
+	report, err := judge.Analyze(ctx, trace, judge.Options{Runner: runner})
+	result.TotalSec = time.Since(start).Seconds()
+	result.Calls = runner.calls
+	if err != nil {
+		result.Status = "error"
+		result.Error = err.Error()
+		return result
+	}
+	writeJSON(filepath.Join(outDir, strings.TrimSuffix(result.Session, ".jsonl")+".report.json"), report)
+
+	if report.Rubric == nil {
+		result.Status = "no-rubric-layer"
+		return result
+	}
+	result.Status = report.Rubric.Status
+	result.Reason = report.Rubric.Reason
+	result.Tasks = len(report.Rubric.Tasks)
+	result.Verdicts = map[string]int{}
+	for _, task := range report.Rubric.Tasks {
+		for _, criterion := range task.Criteria {
+			result.Criteria++
+			switch criterion.Coverage {
+			case model.CoverageSufficient:
+				result.Sufficient++
+			case model.CoveragePartial:
+				result.Partial++
+			case model.CoverageNone:
+				result.None++
+			}
+			if len(criterion.Findings) == 0 {
+				result.Dead++
+			}
+			result.Verdicts[criterion.Verdict]++
+		}
+	}
+	return result
+}
+
+// taskRunes mirrors the pipeline's weak-task-text measurement so threshold
+// calibration can plot outcomes against the signal the gate actually sees.
+func taskRunes(trace *model.Trace) int {
+	total := 0
+	for _, mark := range trace.Marks {
+		if mark.Type != "user-message" {
+			continue
+		}
+		text := strings.TrimSpace(mark.Note)
+		if text == "" || adapter.InjectedUserMessage(text) {
+			continue
+		}
+		total += len([]rune(text))
+	}
+	return total
+}
+
+func printSummary(results []sessionResult) {
+	var scored, degraded, skipped, errored, noLayer int
+	var criteria, sufficient, partial, none, dead int
+	var rubricSecs, scoringSecs, totals []float64
+	taskCounts := map[int]int{}
+	for _, r := range results {
+		switch {
+		case r.Status == "error":
+			errored++
+			continue
+		case r.Status == "no-rubric-layer":
+			noLayer++
+			continue
+		case r.Status == model.RubricStatusScored:
+			scored++
+		case r.Reason == model.RubricReasonGenerationFailed:
+			degraded++
+		default:
+			skipped++
+		}
+		totals = append(totals, r.TotalSec)
+		criteria += r.Criteria
+		sufficient += r.Sufficient
+		partial += r.Partial
+		none += r.None
+		dead += r.Dead
+		if r.Status == model.RubricStatusScored {
+			taskCounts[r.Tasks]++
+		}
+		for _, call := range r.Calls {
+			switch call.Kind {
+			case "rubric":
+				rubricSecs = append(rubricSecs, call.DurationSec)
+			case "scoring-unified":
+				scoringSecs = append(scoringSecs, call.DurationSec)
+			}
+		}
+	}
+	fmt.Println("\n=== M1.5 gate summary ===")
+	fmt.Printf("sessions: %d — scored %d, skipped %d, degraded %d, no-layer %d, error %d\n",
+		len(results), scored, skipped, degraded, noLayer, errored)
+	if criteria > 0 {
+		fmt.Printf("criteria: %d — coverage sufficient %d (%.0f%%), partial %d, none %d; dead %d (%.0f%%)\n",
+			criteria, sufficient, 100*float64(sufficient)/float64(criteria), partial, none,
+			dead, 100*float64(dead)/float64(criteria))
+	}
+	fmt.Printf("task-count distribution (scored sessions): %v\n", taskCounts)
+	fmt.Printf("latency: rubric %s, unified scoring %s, session total %s\n",
+		stats(rubricSecs), stats(scoringSecs), stats(totals))
+}
+
+func stats(xs []float64) string {
+	if len(xs) == 0 {
+		return "n/a"
+	}
+	sort.Float64s(xs)
+	sum := 0.0
+	for _, x := range xs {
+		sum += x
+	}
+	return fmt.Sprintf("median %.0fs mean %.0fs max %.0fs (n=%d)",
+		xs[len(xs)/2], sum/float64(len(xs)), xs[len(xs)-1], len(xs))
+}
+
+func parseTrace(path string) (*model.Trace, error) {
+	abs, err := filepath.Abs(path)
+	if err != nil {
+		return nil, err
+	}
+	var lastErr error
+	for _, source := range []adapter.Source{claudecode.Adapter{}, codex.Adapter{}} {
+		trace, err := source.Parse(abs)
+		if err == nil {
+			return trace, nil
+		}
+		lastErr = err
+	}
+	return nil, lastErr
+}
+
+func writeJSON(path string, v any) {
+	data, err := json.MarshalIndent(v, "", "  ")
+	if err != nil {
+		return
+	}
+	_ = os.WriteFile(path, data, 0o644)
+}