Add session metrics API and per-session totals

[bhaveshpatel640]

Summary

Caller-scoped session metrics for named agents: persist rolled-up per-session totals, and expose meters / chart catalog / chart-data APIs aligned with the ServiceFoundry-style dashboard split.

Closes AGE-2011

Changes

• Persist Session.metrics (total_cost_in_usd, total_duration_ms, total_turns): zero on create; createTurn increments turns; terminal writes fold cost + duration
• Store APIs: getSessionMetricsMeters / getSessionMetricsChartData on InMemory, Postgres, and SQLite (shared builders + inclusion rules)
• HTTP (caller-scoped, fern-ignored):
  • GET /api/v1/sessions/metrics/meters
  • GET /api/v1/sessions/metrics/charts
  • GET /api/v1/sessions/metrics/charts-data
• Duration distributions use total_duration_ms > 0 (not total_turns > 0) so in-flight first turns don’t collapse min/median/p95 to 0ms

How was this tested?

• Unit: packages/trueforge-core session metrics builders + fold (sessionMetrics.test.ts)
• Store contract: InMemory + SQLite (storeContractSuite session metrics cases, including all-12-meters fixture)
• HTTP: packages/trueforge/tests/unit/apis/sessionHttp.test.ts
• Local: pnpm --filter @truefoundry/trueforge-core test (targeted), pnpm --filter @truefoundry/trueforge test:store:sqlite (metrics cases)

Checklist

• I have read the contributing guidelines
• pnpm build, pnpm test, pnpm typecheck, pnpm lint:ci, and pnpm format:check pass locally
• Tests added/updated where it makes sense
• No hand-edits to generated code (packages/trueforge-sdk, .github/fern/openapi/openapi.json, docs/openapi.json) — metrics routes are fern-ignored; fork PRs omit SDK regen; maintainers regenerate after merge
• Docs / .env.example updated if configuration or behavior changed

---

Note

Medium Risk
Introduces new read APIs and a breaking Session wire shape (required metrics), with aggregation logic that must stay consistent across SQLite, Postgres, and in-memory stores.

Overview
Adds session metrics for named agents: rolled-up metrics on every Session response (cost, duration, turns) and three internal GET routes under /api/v1/sessions/metrics/* (Fern-excluded).

Meters (/metrics/meters) aggregate the authenticated caller’s sessions for a given agent_id over an inclusive created_at window (max 30 days), returning 12 fixed meters (totals, cost/session, turn and duration stats with median/p95). Charts (/metrics/charts) expose a static catalog; chart data (/metrics/charts-data) returns zero-filled line series for one chart (sessions_over_time, sessions_cost_over_time, turns_over_time) with hourly buckets for ≤24h windows and daily UTC buckets otherwise.

Shared aggregation lives in sessionMetrics (core) and is wired through ISessionStore into in-memory, SQLite, and Postgres stores (SQL aggregates on the persisted session.metrics JSON). HTTP handlers validate the window and agent existence, then scope queries with created_by from the user context. OpenAPI/docs and SDK types include the new shapes; contract and HTTP tests cover scoping and validation.

^{Reviewed by Cursor Bugbot for commit 5edc0f0. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 5edc0f0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@truefoundry/trueforge-core	Patch
@truefoundry/trueforge	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 98e2416. Configure here.}