Add export v1 contracts and session summary export (kenn-io#991)

This PR turns report/export JSON into explicit v1 contracts for programmatic consumers. It adds shared schema, pricing provenance, and project identity metadata to usage daily and activity report outputs, and introduces a daemonless `agentsview export sessions` summary export for headless analytics. The session export is content-free, supports JSON/NDJSON, and includes per-session usage, model, cost, project, worktree, branch, machine, timestamp, and classification metadata without transcript content.

Pricing provenance is centralized under `internal/export`: reports use a resolver-derived block with source/table metadata, RFC 8785-style digest, fallback indicators, `cost_source`, and a bounded per-model effective rates map. Source-reported costs are marked so consumers know when token-times-rate recomputation is not expected, and reasoning tokens are handled as output-rate billing breakdowns.

Project identity now persists raw observations at sync/import time and recomputes stable identities at export time. Remote-backed identities use normalized network remotes with `sha256:` keys; path-backed fallbacks remain explicit and machine-local. The identity store is preserved through resync and mirrored through PostgreSQL/DuckDB so CLI and HTTP exports stay aligned across backends.

The new session-summary export adds stable watermark/keyset pagination, cursor-reset signaling, `--all`, NDJSON meta rows, root/child and automation filtering, and shared pricing/project metadata. Existing usage/activity payloads stay additive: metadata lands as sibling blocks, and daily breakdown arrays are pinned as arrays rather than omitted.

Docs now describe the v1 contract rules, pricing digest input, project identity derivation, cursor behavior, session-export limits, and default exclusion caveats. Golden fixtures pin usage daily, usage daily with breakdowns, activity report, and session export JSON/NDJSON shapes. Stale `docs/superpowers` design notes were removed, and the shared contract package was renamed from `internal/exportcontracts` to `internal/export`.

Reviewers should focus on:
- shared DTO/resolver code in `internal/export`
- project identity capture, fallback, resync preservation, and mirror-backend persistence
- session summary export query/cursor behavior in `internal/db/session_export.go` and `cmd/agentsview/export.go`
- pricing provenance coupling across SQLite, PostgreSQL, and DuckDB usage/activity paths

The main tradeoff is landing the related export-contract issues together so field names and semantics stay shared across surfaces. This intentionally does not add redaction flags or per-row pricing provenance: raw project paths/remotes are emitted by default, and pricing provenance remains report-level with a bounded per-model map.

Co-authored-by: Wes McKinney <wesm@users.noreply.github.com>

Author: wesm

cmd/agentsview/activity.go

@@ -15,6 +15,7 @@ import (
 	"go.kenn.io/agentsview/internal/activity"
 	"go.kenn.io/agentsview/internal/config"
 	"go.kenn.io/agentsview/internal/db"
+	"go.kenn.io/agentsview/internal/export"
 )
 
 // ActivityReportConfig holds the flags for `agentsview activity report`.
@@ -33,6 +34,8 @@ type ActivityReportConfig struct {
 	Offline  bool
 }
 
+var activityReportNow = time.Now
+
 // runActivityReport syncs, resolves the range, runs the report, and prints it.
 func runActivityReport(cfg ActivityReportConfig) {
 	ctx := context.Background()
@@ -115,6 +118,9 @@ func fetchHTTPActivityReport(
 	if err := json.NewDecoder(resp.Body).Decode(&r); err != nil {
 		return activity.Report{}, err
 	}
+	if r.Projects == nil {
+		r.Projects = map[string]export.ProjectMapEntry{}
+	}
 	return r, nil
 }
 
@@ -154,7 +160,7 @@ func resolveActivityReport(
 		Timezone:       tz,
 		BucketOverride: cfg.Bucket,
 	}
-	q, err := activity.ResolveQuery(input, time.Now())
+	q, err := activity.ResolveQuery(input, activityReportNow())
 	if err != nil {
 		return activity.Report{}, err
 	}
@@ -177,7 +183,7 @@ func todayIn(tz string) string {
 	if err != nil {
 		loc = time.Local
 	}
-	return time.Now().In(loc).Format("2006-01-02")
+	return activityReportNow().In(loc).Format("2006-01-02")
 }
 
 // printActivityReport renders the human-readable report: a header, totals,

cmd/agentsview/activity_test.go

@@ -5,6 +5,7 @@ import (
 	"context"
 	"encoding/json"
 	"net/http"
+	"net/http/httptest"
 	"net/url"
 	"path/filepath"
 	"testing"
@@ -14,8 +15,14 @@ import (
 	"github.com/stretchr/testify/require"
 
 	"go.kenn.io/agentsview/internal/activity"
+	"go.kenn.io/agentsview/internal/config"
 	"go.kenn.io/agentsview/internal/db"
+	"go.kenn.io/agentsview/internal/dbtest"
+	"go.kenn.io/agentsview/internal/export"
+	"go.kenn.io/agentsview/internal/parser"
 	"go.kenn.io/agentsview/internal/pricing"
+	"go.kenn.io/agentsview/internal/server"
+	"go.kenn.io/agentsview/internal/sync"
 )
 
 func TestNewActivityCommand_RegistersReport(t *testing.T) {
@@ -225,6 +232,66 @@ func TestResolveActivityReport_PricesFreshDBUsage(t *testing.T) {
 		"resolveActivityReportPriced must seed fallback pricing for fresh-DB usage")
 }
 
+func TestActivityReportJSONMatchesHTTPExportMetadata(t *testing.T) {
+	dataDir := testDataDir(t)
+	dbPath := filepath.Join(dataDir, "sessions.db")
+	database := dbtest.OpenTestDBAt(t, dbPath)
+	fallbackModel := fallbackPricedModel(t)
+	require.NoError(t, seedFallbackPricing(database))
+	seedUsageDailyExportMetadataFixture(t, database, fallbackModel)
+
+	cliOut := captureStdout(t, func() {
+		runActivityReport(ActivityReportConfig{
+			JSON: true, Preset: "day", Date: "2026-06-01",
+			Timezone: "UTC", Offline: true, NoSync: true,
+		})
+	})
+	var cliReport activity.Report
+	require.NoError(t, json.Unmarshal([]byte(cliOut), &cliReport))
+
+	srv := server.New(config.Config{
+		Host: "127.0.0.1", Port: 0, DataDir: dataDir, DBPath: dbPath,
+		WriteTimeout: 30 * time.Second,
+	}, database, sync.NewEngine(database, sync.EngineConfig{
+		AgentDirs: map[parser.AgentType][]string{
+			parser.AgentClaude: {dataDir},
+		},
+		Machine: "test",
+	}))
+	req := httptest.NewRequest(http.MethodGet,
+		"http://127.0.0.1:0/api/v1/activity/report?"+
+			url.Values{
+				"preset":   {"day"},
+				"date":     {"2026-06-01"},
+				"timezone": {"UTC"},
+			}.Encode(), nil)
+	req.RemoteAddr = "127.0.0.1:1234"
+	w := httptest.NewRecorder()
+	srv.Handler().ServeHTTP(w, req)
+	require.Equal(t, http.StatusOK, w.Code)
+	var httpReport activity.Report
+	require.NoError(t, json.NewDecoder(w.Body).Decode(&httpReport))
+
+	assert.Equal(t, export.ActivityReportSchemaVersion,
+		cliReport.SchemaVersion)
+	assert.Equal(t, cliReport.SchemaVersion, httpReport.SchemaVersion)
+	require.NotNil(t, cliReport.Pricing)
+	require.NotNil(t, httpReport.Pricing)
+	assert.Contains(t, cliReport.Pricing.Models, "gpt-5.1")
+	assert.Contains(t, cliReport.Pricing.Models, fallbackModel)
+	assert.Equal(t, cliReport.Pricing.Models, httpReport.Pricing.Models)
+	require.Contains(t, cliReport.Projects, "shared-project")
+	require.Contains(t, httpReport.Projects, "shared-project")
+	assert.Equal(t, cliReport.Projects, httpReport.Projects)
+	assert.Equal(t, "UTC", cliReport.Timezone)
+	assert.Equal(t, cliReport.Timezone, httpReport.Timezone)
+	assert.Equal(t, cliReport.Totals.Sessions, httpReport.Totals.Sessions)
+	assert.Equal(t, cliReport.Totals.OutputTokens,
+		httpReport.Totals.OutputTokens)
+	assert.NotEmpty(t, cliReport.Buckets)
+	assert.Equal(t, len(cliReport.BySession), len(httpReport.BySession))
+}
+
 func TestRunActivityReportOfflineUsesReadOnlyDBWhenWriteLockHeld(t *testing.T) {
 	dataDir := setupGoldenStatsDataDir(t)
 
@@ -244,3 +311,30 @@ func TestRunActivityReportOfflineUsesReadOnlyDBWhenWriteLockHeld(t *testing.T) {
 	assert.Contains(t, out, "Activity 2026-04-04 to 2026-04-05")
 	assert.Contains(t, out, "Sessions")
 }
+
+func TestActivityReportGolden(t *testing.T) {
+	setupExportGoldenDataDir(t)
+	oldNow := activityReportNow
+	activityReportNow = func() time.Time { return goldenFixtureNow }
+	t.Cleanup(func() { activityReportNow = oldNow })
+
+	cmd := newRootCommand()
+	cmd.SetArgs([]string{
+		"activity", "report",
+		"--json",
+		"--preset", "custom",
+		"--from", "2026-07-03T10:00:00Z",
+		"--to", "2026-07-03T13:00:00Z",
+		"--timezone", "UTC",
+		"--bucket", "1h",
+		"--offline",
+		"--no-sync",
+	})
+	var err error
+	stdout := captureStdout(t, func() {
+		_, err = cmd.ExecuteC()
+	})
+	require.NoError(t, err, "activity report json golden command")
+
+	assertGoldenBytes(t, "activity_report_v1.json", []byte(stdout))
+}

cmd/agentsview/cli.go

@@ -25,8 +25,9 @@ const (
 const dataVersionTooNewExitCode = 3
 
 type cliExitError struct {
-	code int
-	err  error
+	code   int
+	err    error
+	silent bool
 }
 
 func (e *cliExitError) Error() string {
@@ -44,6 +45,13 @@ func withExitCode(err error, code int) error {
 	return &cliExitError{code: code, err: err}
 }
 
+func withSilentExitCode(err error, code int) error {
+	if err == nil {
+		return nil
+	}
+	return &cliExitError{code: code, err: err, silent: true}
+}
+
 func exitCodeFromError(err error) int {
 	var exitErr *cliExitError
 	if errors.As(err, &exitErr) {
@@ -52,6 +60,14 @@ func exitCodeFromError(err error) int {
 	return 1
 }
 
+func isSilentExitError(err error) bool {
+	var exitErr *cliExitError
+	if !errors.As(err, &exitErr) || exitErr == nil {
+		return false
+	}
+	return exitErr.silent
+}
+
 func newRootCommand() *cobra.Command {
 	var showVersion bool
 
@@ -92,6 +108,7 @@ func newRootCommand() *cobra.Command {
 	root.AddCommand(newUpdateCommand())
 	root.AddCommand(newTokenUseCommand())
 	root.AddCommand(newImportCommand())
+	root.AddCommand(newExportCommand())
 	root.AddCommand(newProjectsCommand())
 	root.AddCommand(newHealthCommand())
 	root.AddCommand(newUsageCommand())