feat(analytics): threads and turns now know which client started them

[t3dotgg]

We can't answer basic product questions like "how many people use mobile" or "are threads started on desktop or phone". The server never learns which client sent a request: pairing metadata lumps web and desktop together as "desktop", nothing carries an app version, and events, turns, and PostHog have no client attribution at all.

Now every client announces itself with two optional query params on the /ws upgrade, next to the existing wsTicket: clientSurface (web / desktop / mobile) and clientAppVersion. The server applies them in three places.

• New server-side PostHog events client.connected, client.thread.started, and client.turn.requested carry surface and app version. Client rotation, multi-client users, and per-surface thread starts become plain PostHog queries.
• auth_sessions gets nullable client_surface and client_app_version columns, refreshed on every connect, so rows track the client's current build instead of freezing at pairing.
• The orchestration engine stamps an optional origin into the metadata of every event a client-dispatched command produces. The decider stays pure, and per-thread attribution is queryable in local SQLite.

Every new field is optional on both ends. Old clients send nothing and everything behaves as before. Old servers ignore the unknown params. No UI changes on any surface.

Tested: engine origin stamping, session store partial-update semantics, migration columns, the full server integration suite (125 tests), and typechecks across contracts, client-runtime, server, web, and mobile.

Built by Claude Fable 5 running in Claude Code.

---

Note

Medium Risk
Touches WebSocket auth, session persistence, orchestration event metadata, and analytics. Fields are optional and connect-path failures are best-effort, but this is core connection and event-store plumbing.

Overview
Clients now send optional clientSurface and clientAppVersion on the /ws upgrade so the server can tell web, desktop, and mobile apart (and which build).

On connect, the server records those values on auth_sessions (new nullable columns, COALESCE so partial reports do not wipe earlier data) and emits client.connected. Successful thread.create / thread.turn.start commands emit client.thread.started and client.turn.requested with the same properties.

The orchestration engine stamps an optional origin onto event metadata for client-dispatched commands (including bootstrap sub-commands). The command decider stays pure. Old clients and old servers keep working: missing params are ignored.

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

Note

Track client surface and app version on websocket connections and orchestration events

• Introduces ClientSurface ('web'|'desktop'|'mobile') and OrchestrationClientOrigin contract types; extends AuthClientPresentationMetadata and OrchestrationEventMetadata with optional surface, appVersion, and origin fields
• Mobile, web, and desktop clients now include surface and appVersion in presentation metadata, and the client runtime appends these as clientSurface/clientAppVersion query params on websocket URLs
• On /ws upgrade, the server parses origin from the URL, persists it to the session via SessionStore.recordClientConnection, passes it through makeWsRpcLayer to OrchestrationEngine.dispatch, and stamps origin onto all events produced by that command
• Records client.connected, client.thread.started, and client.turn.requested analytics events with origin props after successful dispatch
• Adds migration 041_AuthSessionClientConnection for nullable client_surface/client_app_version columns on auth_sessions, with COALESCE updates that preserve prior values when nulls are supplied
• Behavioral Change: OrchestrationEngine.dispatch accepts an optional options.origin argument; events now carry metadata.origin when the originating command had one. Invalid or missing origin params are ignored without failing the connection

^{Macroscope summarized 487ea2c.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: aa221fd9-4320-4926-ac08-0f2212c839b4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

One convention issue found: the new AnalyticsService imports use a named tag import instead of the local service-module namespace import used everywhere else in this repo (server.ts, serverRuntimeStartup.ts, provider/Layers/ProviderService.ts). Everything else in the diff (dispatch origin plumbing, SessionStore.recordClientConnection, AuthSessionRepository.setClientConnection, migration 041, contracts schemas) follows the service, error, and dependency-acquisition conventions.

^{Posted via Macroscope — Effect Service Conventions}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.4 KiB	13.4 KiB	+1 B (+0.0%)	15.1 KiB	✅
Codex	Thread snapshot wire	6.9 KiB	6.9 KiB	−4 B (−0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.5 KiB	6.5 KiB	+5 B (+0.1%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	55.0 KiB	55.0 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	16	16	0 (0.0%)	21	✅
Claude	Total thread wire	13.5 KiB	13.5 KiB	+5 B (+0.0%)	15.1 KiB	✅
Claude	Thread snapshot wire	6.9 KiB	6.9 KiB	0 B (0.0%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.6 KiB	6.6 KiB	+5 B (+0.1%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	55.8 KiB	55.8 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	16	16	0 (0.0%)	21	✅

Baseline: be7d35a · PR result: 487ea2c · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 109.4 KiB
• Claude decoded thread snapshot: 110.1 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[cursor]

Cursor Bugbot has reviewed your changes using high 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 36694fb. Configure here.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR introduces a new client origin tracking feature with database schema changes, new analytics events, and modifications to the core orchestration dispatch flow. Additionally, there is an unresolved medium-severity finding about analytics firing before dispatch succeeds. Human review is warranted.

^{You can add or adjust custom eligibility rules. Learn more.}