Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
feat(analytics): threads and turns now know which client started them (#7774)
Theo Browne11f051373e79
diff --git a/apps/mobile/src/connection/platform.ts b/apps/mobile/src/connection/platform.tsindex 852535d9d..8e699e4c2 100644--- a/apps/mobile/src/connection/platform.ts+++ b/apps/mobile/src/connection/platform.ts@@ -21,6 +21,7 @@ import * as Layer from "effect/Layer";import * as Option from "effect/Option";import * as Queue from "effect/Queue";import * as Stream from "effect/Stream";+import Constants from "expo-constants";import * as Network from "expo-network";import { AppState } from "react-native";@@ -166,7 +167,7 @@ const capabilitiesLayer = Layer.effectContext(Context.add(ClientPresentation,ClientPresentation.of({- metadata: authClientMetadata(),+ metadata: authClientMetadata(Constants.expoConfig?.version),scopes: AuthStandardClientScopes,}),),diff --git a/apps/mobile/src/lib/authClientMetadata.ts b/apps/mobile/src/lib/authClientMetadata.tsindex 09897b618..5189c34f5 100644--- a/apps/mobile/src/lib/authClientMetadata.ts+++ b/apps/mobile/src/lib/authClientMetadata.ts@@ -1,10 +1,12 @@import type { AuthClientPresentationMetadata } from "@t3tools/contracts";import { Platform } from "react-native";-export function authClientMetadata(): AuthClientPresentationMetadata {+export function authClientMetadata(appVersion?: string): AuthClientPresentationMetadata {return {label: "T3 Code Mobile",deviceType: "mobile",...(Platform.OS === "ios" ? { os: "iOS" } : Platform.OS === "android" ? { os: "Android" } : {}),+ surface: "mobile",+ ...(appVersion ? { appVersion } : {}),};}diff --git a/apps/mobile/src/lib/connection.test.ts b/apps/mobile/src/lib/connection.test.tsindex f1f30b298..8ec0fb8bd 100644--- a/apps/mobile/src/lib/connection.test.ts+++ b/apps/mobile/src/lib/connection.test.ts@@ -26,6 +26,14 @@ describe("mobile remote connection records", () => {label: "T3 Code Mobile",deviceType: "mobile",os: "iOS",+ surface: "mobile",+ });+ });++ it("includes the mobile app version when the client provides it", () => {+ expect(authClientMetadata("1.2.3")).toMatchObject({+ surface: "mobile",+ appVersion: "1.2.3",});});diff --git a/apps/server/src/auth/SessionStore.test.ts b/apps/server/src/auth/SessionStore.test.tsindex 334c24ef5..1fb01c1f0 100644--- a/apps/server/src/auth/SessionStore.test.ts+++ b/apps/server/src/auth/SessionStore.test.ts@@ -4,6 +4,7 @@ import * as Duration from "effect/Duration";import * as Effect from "effect/Effect";import * as Layer from "effect/Layer";import * as TestClock from "effect/testing/TestClock";+import * as SqlClient from "effect/unstable/sql/SqlClient";import * as ServerConfig from "../config.ts";import { PersistenceSqlError } from "../persistence/Errors.ts";@@ -47,6 +48,7 @@ const failingSessionLookupRepositoryLayer = Layer.succeed(AuthSessions.AuthSessirevoke: () => Effect.fail(repositoryFailure),revokeAllExcept: () => Effect.fail(repositoryFailure),setLastConnectedAt: () => Effect.void,+ setClientConnection: () => Effect.void,});const failingSessionLookupCredentialLayer = Layer.effect(@@ -315,4 +317,35 @@ it.layer(NodeServices.layer)("SessionStore.layer", (it) => {expect(afterReconnect[0]?.lastConnectedAt?.toString()).not.toBe(firstConnectedAt?.toString());}).pipe(Effect.provide(Layer.merge(makeSessionStoreLayer(), TestClock.layer()))),);+ it.effect("records client connection metadata without clearing prior values", () =>+ Effect.gen(function* () {+ const sessions = yield* SessionStore.SessionStore;+ const sql = yield* SqlClient.SqlClient;+ const issued = yield* sessions.issue({+ subject: "client-connection-test",+ method: "bearer-access-token",+ });+ const readRow = sql<{+ readonly surface: string | null;+ readonly appVersion: string | null;+ }>`+ SELECT client_surface AS "surface", client_app_version AS "appVersion"+ FROM auth_sessions+ WHERE session_id = ${issued.sessionId}+ `;++ yield* sessions.recordClientConnection(issued.sessionId, {+ surface: "mobile",+ appVersion: "1.2.0",+ });+ expect((yield* readRow)[0]).toEqual({ surface: "mobile", appVersion: "1.2.0" });++ // A partial report (old or minimal client) must not null out stored data.+ yield* sessions.recordClientConnection(issued.sessionId, { appVersion: "1.3.0" });+ expect((yield* readRow)[0]).toEqual({ surface: "mobile", appVersion: "1.3.0" });++ yield* sessions.recordClientConnection(issued.sessionId, {});+ expect((yield* readRow)[0]).toEqual({ surface: "mobile", appVersion: "1.3.0" });+ }).pipe(Effect.provide(Layer.mergeAll(makeSessionStoreLayer(), SqlitePersistenceMemory))),+ );});diff --git a/apps/server/src/auth/SessionStore.ts b/apps/server/src/auth/SessionStore.tsindex 40a1c43e0..cdcd4a1ac 100644--- a/apps/server/src/auth/SessionStore.ts+++ b/apps/server/src/auth/SessionStore.ts@@ -5,6 +5,7 @@ import {type AuthClientMetadata,type AuthClientSession,type AuthEnvironmentScope,+ type ClientSurface,type ServerAuthSessionMethod,} from "@t3tools/contracts";import * as Context from "effect/Context";@@ -396,6 +397,13 @@ export class SessionStore extends Context.Service<) => Effect.Effect<number, SessionCredentialInternalError>;readonly markConnected: (sessionId: AuthSessionId) => Effect.Effect<void, never>;readonly markDisconnected: (sessionId: AuthSessionId) => Effect.Effect<void, never>;+ readonly recordClientConnection: (+ sessionId: AuthSessionId,+ client: {+ readonly surface?: ClientSurface | undefined;+ readonly appVersion?: string | undefined;+ },+ ) => Effect.Effect<void, never>;}>()("t3/auth/SessionStore") {}@@ -544,6 +552,28 @@ export const make = Effect.gen(function* () {Effect.withSpan("SessionStore.markConnected"),);+ // Best-effort: connection metadata must never block or fail a connect.+ const recordClientConnection: SessionStore["Service"]["recordClientConnection"] = (+ sessionId,+ client,+ ) =>+ client.surface === undefined && client.appVersion === undefined+ ? Effect.void+ : authSessions+ .setClientConnection({+ sessionId,+ surface: client.surface ?? null,+ appVersion: client.appVersion ?? null,+ })+ .pipe(+ Effect.catchCause((cause) =>+ Effect.logWarning("Failed to record session client connection metadata.").pipe(+ Effect.annotateLogs({ sessionId, cause }),+ ),+ ),+ Effect.withSpan("SessionStore.recordClientConnection"),+ );+const markDisconnected: SessionStore["Service"]["markDisconnected"] = (sessionId) =>Ref.update(connectedSessionsRef, (current) => {const next = new Map(current);@@ -912,6 +942,7 @@ export const make = Effect.gen(function* () {revokeAllExcept,markConnected,markDisconnected,+ recordClientConnection,});});diff --git a/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts b/apps/server/src/orchestration/Layers/OrchestrationEngine.test.tsindex 1b89d6d4d..382c253fe 100644--- a/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts+++ b/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts@@ -1379,4 +1379,55 @@ describe("OrchestrationEngine", () => {await system.dispose();});++ it("stamps the dispatching client's origin onto persisted event metadata", async () => {+ const createdAt = now();+ const system = await createOrchestrationSystem();+ const { engine } = system;++ await system.run(+ engine.dispatch(+ {+ type: "project.create",+ commandId: CommandId.make("cmd-origin-project-create"),+ projectId: asProjectId("project-origin"),+ title: "Origin Project",+ workspaceRoot: "/tmp/project-origin",+ defaultModelSelection: {+ instanceId: ProviderInstanceId.make("codex"),+ model: "gpt-5-codex",+ },+ createdAt,+ },+ { origin: { surface: "mobile", appVersion: "1.2.3" } },+ ),+ );+ await system.run(+ engine.dispatch({+ type: "project.create",+ commandId: CommandId.make("cmd-no-origin-project-create"),+ projectId: asProjectId("project-no-origin"),+ title: "No Origin Project",+ workspaceRoot: "/tmp/project-no-origin",+ defaultModelSelection: {+ instanceId: ProviderInstanceId.make("codex"),+ model: "gpt-5-codex",+ },+ createdAt,+ }),+ );++ const events = await system.run(+ Stream.runCollect(engine.readEvents(0)).pipe(Effect.map((chunk) => Array.from(chunk))),+ );+ const withOrigin = events.find((event) => event.commandId === "cmd-origin-project-create");+ const withoutOrigin = events.find(+ (event) => event.commandId === "cmd-no-origin-project-create",+ );++ expect(withOrigin?.metadata.origin).toEqual({ surface: "mobile", appVersion: "1.2.3" });+ expect(withoutOrigin?.metadata.origin).toBeUndefined();++ await system.dispose();+ });});diff --git a/apps/server/src/orchestration/Layers/OrchestrationEngine.ts b/apps/server/src/orchestration/Layers/OrchestrationEngine.tsindex da79b4395..423a44a6f 100644--- a/apps/server/src/orchestration/Layers/OrchestrationEngine.ts+++ b/apps/server/src/orchestration/Layers/OrchestrationEngine.ts@@ -1,4 +1,5 @@import type {+ OrchestrationClientOrigin,OrchestrationEvent,OrchestrationReadModel,ProjectId,@@ -54,6 +55,7 @@ const isOrchestrationCommandInvariantError = Schema.is(OrchestrationCommandInvarinterface CommandEnvelope {command: OrchestrationCommand;+ origin: OrchestrationClientOrigin | undefined;result: Deferred.Deferred<{ sequence: number }, OrchestrationDispatchError>;startedAtMs: number;}@@ -182,7 +184,16 @@ const makeOrchestrationEngine = Effect.gen(function* () {}),),);- const eventBases = Array.isArray(eventBase) ? eventBase : [eventBase];+ const plannedEvents = Array.isArray(eventBase) ? eventBase : [eventBase];+ // Stamp the dispatching client's origin onto every event the command+ // produced. The decider stays pure; attribution is an engine concern.+ const eventBases =+ envelope.origin === undefined+ ? plannedEvents+ : plannedEvents.map((planned) => ({+ ...planned,+ metadata: { ...planned.metadata, origin: envelope.origin },+ }));const committedCommand = yield* sql.withTransaction(Effect.gen(function* () {@@ -329,11 +340,12 @@ const makeOrchestrationEngine = Effect.gen(function* () {const readEvents: OrchestrationEngineShape["readEvents"] = (fromSequenceExclusive, limit) =>eventStore.readFromSequence(fromSequenceExclusive, limit);- const dispatch: OrchestrationEngineShape["dispatch"] = (command) =>+ const dispatch: OrchestrationEngineShape["dispatch"] = (command, options) =>Effect.gen(function* () {const result = yield* Deferred.make<{ sequence: number }, OrchestrationDispatchError>();yield* Queue.offer(commandQueue, {command,+ origin: options?.origin,result,startedAtMs: yield* Clock.currentTimeMillis,});diff --git a/apps/server/src/orchestration/Services/OrchestrationEngine.ts b/apps/server/src/orchestration/Services/OrchestrationEngine.tsindex f8bcfd76a..a32a45684 100644--- a/apps/server/src/orchestration/Services/OrchestrationEngine.ts+++ b/apps/server/src/orchestration/Services/OrchestrationEngine.ts@@ -10,7 +10,11 @@** @module OrchestrationEngineService*/-import type { OrchestrationCommand, OrchestrationEvent } from "@t3tools/contracts";+import type {+ OrchestrationClientOrigin,+ OrchestrationCommand,+ OrchestrationEvent,+} from "@t3tools/contracts";import * as Context from "effect/Context";import type * as Effect from "effect/Effect";import type * as Stream from "effect/Stream";@@ -41,6 +45,8 @@ export interface OrchestrationEngineShape {* Dispatch a validated orchestration command.** @param command - Valid orchestration command.+ * @param options - Optional client origin (surface/app version) stamped into+ * the metadata of every event the command produces.* @returns Effect containing the sequence of the persisted event.** Dispatch is serialized through an internal queue and deduplicated via@@ -48,6 +54,7 @@ export interface OrchestrationEngineShape {*/readonly dispatch: (command: OrchestrationCommand,+ options?: { readonly origin?: OrchestrationClientOrigin },) => Effect.Effect<{ sequence: number }, OrchestrationDispatchError, never>;/**diff --git a/apps/server/src/persistence/AuthSessions.ts b/apps/server/src/persistence/AuthSessions.tsindex 545688e38..579d3a608 100644--- a/apps/server/src/persistence/AuthSessions.ts+++ b/apps/server/src/persistence/AuthSessions.ts@@ -10,6 +10,7 @@ import {AuthClientMetadataDeviceType,AuthEnvironmentScopes,AuthSessionId,+ ClientSurface,ServerAuthSessionMethod,} from "@t3tools/contracts";@@ -82,6 +83,13 @@ export const SetAuthSessionLastConnectedAtInput = Schema.Struct({});export type SetAuthSessionLastConnectedAtInput = typeof SetAuthSessionLastConnectedAtInput.Type;+export const SetAuthSessionClientConnectionInput = Schema.Struct({+ sessionId: AuthSessionId,+ surface: Schema.NullOr(ClientSurface),+ appVersion: Schema.NullOr(Schema.String),+});+export type SetAuthSessionClientConnectionInput = typeof SetAuthSessionClientConnectionInput.Type;+export class AuthSessionRepository extends Context.Service<AuthSessionRepository,{@@ -103,6 +111,9 @@ export class AuthSessionRepository extends Context.Service<readonly setLastConnectedAt: (input: SetAuthSessionLastConnectedAtInput,) => Effect.Effect<void, AuthSessionRepositoryError>;+ readonly setClientConnection: (+ input: SetAuthSessionClientConnectionInput,+ ) => Effect.Effect<void, AuthSessionRepositoryError>;}>()("t3/persistence/AuthSessions/AuthSessionRepository") {}@@ -281,6 +292,20 @@ export const make = Effect.gen(function* () {`,});+ // COALESCE keeps the previous value when a client reports only one field, so+ // a partial report never nulls out data a fuller client stored earlier.+ const setClientConnectionRow = SqlSchema.void({+ Request: SetAuthSessionClientConnectionInput,+ execute: ({ sessionId, surface, appVersion }) =>+ sql`+ UPDATE auth_sessions+ SET client_surface = COALESCE(${surface}, client_surface),+ client_app_version = COALESCE(${appVersion}, client_app_version)+ WHERE session_id = ${sessionId}+ AND revoked_at IS NULL+ `,+ });+const revokeSessionRows = SqlSchema.findAll({Request: RevokeAuthSessionInput,Result: Schema.Struct({ sessionId: AuthSessionId }),@@ -404,6 +429,17 @@ export const make = Effect.gen(function* () {),);+ const setClientConnection: AuthSessionRepository["Service"]["setClientConnection"] = (input) =>+ setClientConnectionRow(input).pipe(+ Effect.mapError(+ toPersistenceSqlOrDecodeError(+ "AuthSessionRepository.setClientConnection:query",+ "AuthSessionRepository.setClientConnection:encodeRequest",+ { sessionId: input.sessionId },+ ),+ ),+ );+return {create,getById,@@ -411,6 +447,7 @@ export const make = Effect.gen(function* () {revoke,revokeAllExcept,setLastConnectedAt,+ setClientConnection,} satisfies AuthSessionRepository["Service"];});diff --git a/apps/server/src/persistence/Migrations.ts b/apps/server/src/persistence/Migrations.tsindex b137cedfb..170cb3992 100644--- a/apps/server/src/persistence/Migrations.ts+++ b/apps/server/src/persistence/Migrations.ts@@ -53,6 +53,7 @@ import Migration0037 from "./Migrations/037_ProjectionTurnsKeysetIndex.ts";import Migration0038 from "./Migrations/038_ProjectionThreadsPinOrderKey.ts";import Migration0039 from "./Migrations/039_ProjectionProjectsDefaultThreadEnvMode.ts";import Migration0040 from "./Migrations/040_ProjectionProjectFaviconPath.ts";+import Migration0041 from "./Migrations/041_AuthSessionClientConnection.ts";/*** Migration loader with all migrations defined inline.@@ -105,6 +106,7 @@ export const migrationEntries = [[38, "ProjectionThreadsPinOrderKey", Migration0038],[39, "ProjectionProjectsDefaultThreadEnvMode", Migration0039],[40, "ProjectionProjectFaviconPath", Migration0040],+ [41, "AuthSessionClientConnection", Migration0041],] as const;export const migrationManifest = migrationEntries.map(([id, name]) => [id, name] as const);diff --git a/apps/server/src/persistence/Migrations/041_AuthSessionClientConnection.test.ts b/apps/server/src/persistence/Migrations/041_AuthSessionClientConnection.test.tsnew file mode 100644index 000000000..178338b78--- /dev/null+++ b/apps/server/src/persistence/Migrations/041_AuthSessionClientConnection.test.ts@@ -0,0 +1,31 @@+import { assert, it } from "@effect/vitest";+import * as Effect from "effect/Effect";+import * as Layer from "effect/Layer";+import * as SqlClient from "effect/unstable/sql/SqlClient";++import { runMigrations } from "../Migrations.ts";+import * as NodeSqliteClient from "../NodeSqliteClient.ts";++const layer = it.layer(Layer.mergeAll(NodeSqliteClient.layerMemory()));++layer("041_AuthSessionClientConnection", (it) => {+ it.effect("adds nullable client surface and app version columns to auth sessions", () =>+ Effect.gen(function* () {+ const sql = yield* SqlClient.SqlClient;++ yield* runMigrations({ toMigrationInclusive: 40 });+ yield* runMigrations({ toMigrationInclusive: 41 });++ const columns = yield* sql<{ readonly name: string; readonly notnull: number }>`+ PRAGMA table_info(auth_sessions)+ `;+ const surface = columns.find((column) => column.name === "client_surface");+ const appVersion = columns.find((column) => column.name === "client_app_version");++ assert.equal(surface?.name, "client_surface");+ assert.equal(surface?.notnull, 0);+ assert.equal(appVersion?.name, "client_app_version");+ assert.equal(appVersion?.notnull, 0);+ }),+ );+});diff --git a/apps/server/src/persistence/Migrations/041_AuthSessionClientConnection.ts b/apps/server/src/persistence/Migrations/041_AuthSessionClientConnection.tsnew file mode 100644index 000000000..2194c3cd0--- /dev/null+++ b/apps/server/src/persistence/Migrations/041_AuthSessionClientConnection.ts@@ -0,0 +1,26 @@+import * as Effect from "effect/Effect";+import * as SqlClient from "effect/unstable/sql/SqlClient";++// Client-declared surface (web/desktop/mobile) and app version, refreshed on+// every WebSocket connect so the row tracks the client's current build instead+// of freezing at session issuance. Nullable: old clients never report them.+export default Effect.gen(function* () {+ const sql = yield* SqlClient.SqlClient;+ const columns = yield* sql<{ readonly name: string }>`+ PRAGMA table_info(auth_sessions)+ `;++ if (!columns.some((column) => column.name === "client_surface")) {+ yield* sql`+ ALTER TABLE auth_sessions+ ADD COLUMN client_surface TEXT+ `;+ }++ if (!columns.some((column) => column.name === "client_app_version")) {+ yield* sql`+ ALTER TABLE auth_sessions+ ADD COLUMN client_app_version TEXT+ `;+ }+});diff --git a/apps/server/src/server.test.ts b/apps/server/src/server.test.tsindex 7cda53f25..de3f5101f 100644--- a/apps/server/src/server.test.ts+++ b/apps/server/src/server.test.ts@@ -151,6 +151,7 @@ import * as NativeTelemetryClient from "./resourceTelemetry/NativeTelemetryClienimport * as ResourceAttribution from "./resourceTelemetry/ResourceAttribution.ts";import * as ResourceTelemetry from "./resourceTelemetry/ResourceTelemetry.ts";import * as UsageService from "./usage/UsageService.ts";+import * as AnalyticsService from "./telemetry/AnalyticsService.ts";import * as Data from "effect/Data";import { makeOrchestrationIntegrationHarness } from "../integration/OrchestrationEngineHarness.integration.ts";@@ -402,6 +403,7 @@ const buildAppUnderTest = (options?: {>;terminalManager?: Partial<TerminalManager.TerminalManager["Service"]>;orchestrationEngine?: Partial<OrchestrationEngine.OrchestrationEngineService["Service"]>;+ analyticsService?: Partial<AnalyticsService.AnalyticsService["Service"]>;projectionSnapshotQuery?: Partial<ProjectionSnapshotQuery.ProjectionSnapshotQuery["Service"]>;checkpointDiffQuery?: Partial<CheckpointDiffQuery.CheckpointDiffQuery["Service"]>;browserTraceCollector?: Partial<BrowserTraceCollector.BrowserTraceCollector["Service"]>;@@ -833,6 +835,13 @@ const buildAppUnderTest = (options?: {const appLayer = servedRoutesLayer.pipe(Layer.provide(resourceTelemetryLayer),Layer.provide(UsageService.layerTest),+ Layer.provide(+ Layer.mock(AnalyticsService.AnalyticsService)({+ record: () => Effect.void,+ flush: Effect.void,+ ...options?.layers?.analyticsService,+ }),+ ),Layer.provide(Layer.mock(BrowserTraceCollector.BrowserTraceCollector)({record: () => Effect.void,@@ -5035,6 +5044,93 @@ it.layer(NodeServices.layer)("server router seam", (it) => {}).pipe(Effect.provide(NodeHttpServer.layerTest)),);+ it.effect("records thread analytics only after a client command succeeds", () =>+ Effect.gen(function* () {+ const effects: string[] = [];+ const analyticsProperties: Array<Readonly<Record<string, unknown>> | undefined> = [];+ const failedCommandId = CommandId.make("cmd-thread-create-failed");++ yield* buildAppUnderTest({+ layers: {+ analyticsService: {+ record: (event, properties) =>+ Effect.sync(() => {+ effects.push(`analytics:${event}`);+ analyticsProperties.push(properties);+ }),+ },+ orchestrationEngine: {+ dispatch: (command) =>+ Effect.sync(() => effects.push(`dispatch:${command.commandId}`)).pipe(+ Effect.flatMap(() =>+ command.commandId === failedCommandId+ ? Effect.fail(+ new OrchestrationListenerCallbackError({+ listener: "domain-event",+ detail: "thread creation failed",+ }),+ )+ : Effect.succeed({ sequence: 1 }),+ ),+ ),+ },+ },+ });++ const createThreadCommand = (commandId: CommandId, threadId: ThreadId) =>+ ({+ type: "thread.create",+ commandId,+ threadId,+ projectId: defaultProjectId,+ title: "Analytics test",+ modelSelection: defaultModelSelection,+ runtimeMode: "full-access",+ interactionMode: "default",+ branch: null,+ worktreePath: null,+ createdAt: "2026-01-01T00:00:00.000Z",+ }) as const;++ const wsUrl = yield* getWsServerUrl("/ws?clientSurface=mobile&clientAppVersion=1.2.3");+ yield* Effect.scoped(+ withWsRpcClient(wsUrl, (client) =>+ Effect.gen(function* () {+ const failed = yield* client[ORCHESTRATION_WS_METHODS.dispatchCommand](+ createThreadCommand(failedCommandId, ThreadId.make("thread-create-failed")),+ ).pipe(Effect.result);++ assert.equal(failed._tag, "Failure");+ assert.deepEqual(effects, [+ "analytics:client.connected",+ "dispatch:cmd-thread-create-failed",+ ]);++ const succeeded = yield* client[ORCHESTRATION_WS_METHODS.dispatchCommand](+ createThreadCommand(+ CommandId.make("cmd-thread-create-succeeded"),+ ThreadId.make("thread-create-succeeded"),+ ),+ );++ assert.equal(succeeded.sequence, 1);+ }),+ ),+ );++ assert.deepEqual(effects, [+ "analytics:client.connected",+ "dispatch:cmd-thread-create-failed",+ "dispatch:cmd-thread-create-succeeded",+ "analytics:client.thread.started",+ ]);+ assert.deepEqual(analyticsProperties, [+ { surface: "mobile", appVersion: "1.2.3" },+ { surface: "mobile", appVersion: "1.2.3" },+ ]);+ }).pipe(Effect.provide(NodeHttpServer.layerTest)),+ );+it.effect("routes websocket rpc projects.writeFile errors", () =>Effect.gen(function* () {const fs = yield* FileSystem.FileSystem;diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.tsindex c5b7e50a8..c3caea225 100644--- a/apps/server/src/ws.ts+++ b/apps/server/src/ws.ts@@ -15,9 +15,11 @@ import {type AuthAccessStreamEvent,type AuthEnvironmentScope,AuthSessionId,+ ClientSurface,CommandId,type DiscoveredLocalServerList,EventId,+ type OrchestrationClientOrigin,type OrchestrationCommand,type GitActionProgressEvent,type GitManagerServiceError,@@ -106,6 +108,7 @@ import { requiredScopeForRpcMethod } from "./auth/RpcAuthorization.ts";import * as ProcessDiagnostics from "./diagnostics/ProcessDiagnostics.ts";import * as ProcessResourceMonitor from "./diagnostics/ProcessResourceMonitor.ts";import * as ResourceTelemetry from "./resourceTelemetry/ResourceTelemetry.ts";+import * as AnalyticsService from "./telemetry/AnalyticsService.ts";import * as UsageService from "./usage/UsageService.ts";import * as TraceDiagnostics from "./diagnostics/TraceDiagnostics.ts";import * as PullRequestService from "./pullRequest/PullRequestService.ts";@@ -349,8 +352,37 @@ function toAuthAccessStreamEvent(}}+const isClientSurface = Schema.is(ClientSurface);+const MAX_CLIENT_APP_VERSION_LENGTH = 64;++// Optional client identity announced on the /ws upgrade URL next to wsTicket.+// Lenient by design: absent or malformed values degrade to {} so a connection+// never fails over attribution metadata.+function readClientConnectionOrigin(+ request: HttpServerRequest.HttpServerRequest,+): OrchestrationClientOrigin {+ const url = HttpServerRequest.toURL(request);+ if (Option.isNone(url)) {+ return {};+ }+ const surface = url.value.searchParams.get("clientSurface");+ const appVersion = url.value.searchParams.get("clientAppVersion")?.trim() ?? "";+ return {+ ...(isClientSurface(surface) ? { surface } : {}),+ ...(appVersion !== "" && appVersion.length <= MAX_CLIENT_APP_VERSION_LENGTH+ ? { appVersion }+ : {}),+ };+}++const clientOriginAnalyticsProps = (origin: OrchestrationClientOrigin) => ({+ ...(origin.surface !== undefined ? { surface: origin.surface } : {}),+ ...(origin.appVersion !== undefined ? { appVersion: origin.appVersion } : {}),+});+const makeWsRpcLayer = (currentSession: EnvironmentAuth.AuthenticatedSession,+ clientOrigin: OrchestrationClientOrigin,previewAutomationBroker: PreviewAutomationBroker.PreviewAutomationBroker["Service"],) =>WsRpcGroup.toLayer(@@ -359,6 +391,35 @@ const makeWsRpcLayer = (const crypto = yield* Crypto.Crypto;const projectionSnapshotQuery = yield* ProjectionSnapshotQuery.ProjectionSnapshotQuery;const orchestrationEngine = yield* OrchestrationEngine.OrchestrationEngineService;+ const analytics = yield* AnalyticsService.AnalyticsService;+ // Every command dispatched on this connection carries the connecting+ // client's origin, including server-generated bootstrap sub-commands:+ // the client's request caused them.+ const hasClientOrigin =+ clientOrigin.surface !== undefined || clientOrigin.appVersion !== undefined;+ const dispatchFromClient: OrchestrationEngine.OrchestrationEngineShape["dispatch"] = (+ command,+ ) =>+ orchestrationEngine.dispatch(+ command,+ hasClientOrigin ? { origin: clientOrigin } : undefined,+ );+ const originProps = clientOriginAnalyticsProps(clientOrigin);+ const recordClientCommandAnalytics = (command: OrchestrationCommand) => {+ switch (command.type) {+ case "thread.create":+ return analytics.record("client.thread.started", originProps);+ case "thread.turn.start":+ return command.bootstrap?.createThread+ ? Effect.andThen(+ analytics.record("client.thread.started", originProps),+ analytics.record("client.turn.requested", originProps),+ )+ : analytics.record("client.turn.requested", originProps);+ default:+ return Effect.void;+ }+ };const checkpointDiffQuery = yield* CheckpointDiffQuery.CheckpointDiffQuery;const keybindings = yield* Keybindings.Keybindings;const externalLauncher = yield* ExternalLauncher.ExternalLauncher;@@ -514,7 +575,7 @@ const makeWsRpcLayer = (activityId: serverEventId,}).pipe(Effect.flatMap(({ commandId, activityId }) =>- orchestrationEngine.dispatch({+ dispatchFromClient({type: "thread.activity.append",commandId,threadId: input.threadId,@@ -769,7 +830,7 @@ const makeWsRpcLayer = (createdThread? serverCommandId("bootstrap-thread-delete").pipe(Effect.flatMap((commandId) =>- orchestrationEngine.dispatch({+ dispatchFromClient({type: "thread.delete",commandId,threadId: command.threadId,@@ -896,7 +957,7 @@ const makeWsRpcLayer = (const bootstrapProgram = Effect.gen(function* () {if (bootstrap?.createThread) {- yield* orchestrationEngine.dispatch({+ yield* dispatchFromClient({type: "thread.create",commandId: yield* serverCommandId("bootstrap-thread-create"),threadId: command.threadId,@@ -943,7 +1004,7 @@ const makeWsRpcLayer = (path: null,});targetWorktreePath = worktree.worktree.path;- yield* orchestrationEngine.dispatch({+ yield* dispatchFromClient({type: "thread.meta.update",commandId: yield* serverCommandId("bootstrap-thread-meta-update"),threadId: command.threadId,@@ -955,7 +1016,7 @@ const makeWsRpcLayer = (yield* runSetupProgram();- return yield* orchestrationEngine.dispatch(finalTurnStartCommand);+ return yield* dispatchFromClient(finalTurnStartCommand);});return yield* bootstrapProgram.pipe(@@ -995,13 +1056,11 @@ const makeWsRpcLayer = (const dispatchEffect =normalizedCommand.type === "thread.turn.start" && normalizedCommand.bootstrap? dispatchBootstrapTurnStart(normalizedCommand)- : orchestrationEngine- .dispatch(normalizedCommand)- .pipe(- Effect.mapError((cause) =>- toDispatchCommandError(cause, "Failed to dispatch orchestration command"),- ),- );+ : dispatchFromClient(normalizedCommand).pipe(+ Effect.mapError((cause) =>+ toDispatchCommandError(cause, "Failed to dispatch orchestration command"),+ ),+ );return startup.enqueueCommand(dispatchEffect)@@ -1098,6 +1157,7 @@ const makeWsRpcLayer = (): false;const result = yield* dispatchNormalizedCommand(normalizedCommand);+ yield* recordClientCommandAnalytics(normalizedCommand);if (parkingCommand) {const parkingKind = parkingCommand.type === "thread.archive" ? "archive" : "settle";if (shouldStopSessionAfterCommand) {@@ -2330,6 +2390,7 @@ export const websocketRpcRouteLayer = Layer.unwrap(const request = yield* HttpServerRequest.HttpServerRequest;const serverAuth = yield* EnvironmentAuth.EnvironmentAuth;const sessions = yield* SessionStore.SessionStore;+ const analytics = yield* AnalyticsService.AnalyticsService;const session = yield* serverAuth.authenticateWebSocketUpgrade(request).pipe(Effect.catchIf(EnvironmentAuth.isServerAuthCredentialError, (error) =>failEnvironmentAuthInvalid(EnvironmentAuth.serverAuthCredentialReason(error)),@@ -2338,11 +2399,14 @@ export const websocketRpcRouteLayer = Layer.unwrap(failEnvironmentInternal("internal_error", error),),);+ const clientOrigin = readClientConnectionOrigin(request);+ yield* sessions.recordClientConnection(session.sessionId, clientOrigin);+ yield* analytics.record("client.connected", clientOriginAnalyticsProps(clientOrigin));const rpcWebSocketHttpEffect = yield* RpcServer.toHttpEffectWebsocket(WsRpcGroup, {disableTracing: true,}).pipe(Effect.provide(- makeWsRpcLayer(session, previewAutomationBroker).pipe(+ makeWsRpcLayer(session, clientOrigin, previewAutomationBroker).pipe(Layer.provideMerge(RpcSerialization.layerJson),Layer.provide(ProviderMaintenanceRunner.layer),Layer.provide(Layer.succeed(ServerSelfUpdate.ServerSelfUpdate, serverSelfUpdate)),diff --git a/apps/web/src/connection/platform.ts b/apps/web/src/connection/platform.tsindex c7652136f..daead0bc6 100644--- a/apps/web/src/connection/platform.ts+++ b/apps/web/src/connection/platform.ts@@ -42,6 +42,7 @@ import * as Ref from "effect/Ref";import * as Stream from "effect/Stream";import { FetchHttpClient } from "effect/unstable/http";+import { APP_VERSION } from "../branding";import { readDesktopPrimaryBearerToken } from "../environments/primary/desktopAuth";import { primaryEnvironmentHttpLayer } from "../environments/primary/httpLayer";import {@@ -120,6 +121,8 @@ function clientMetadata() {label: desktop ? "T3 Code Desktop" : "T3 Code Web",deviceType: "desktop" as const,...(platform === "" ? {} : { os: platform }),+ surface: desktop ? ("desktop" as const) : ("web" as const),+ ...(APP_VERSION === "0.0.0" ? {} : { appVersion: APP_VERSION }),};}diff --git a/packages/client-runtime/src/authorization/remote.ts b/packages/client-runtime/src/authorization/remote.tsindex 69c157d0e..895fee836 100644--- a/packages/client-runtime/src/authorization/remote.ts+++ b/packages/client-runtime/src/authorization/remote.ts@@ -32,6 +32,20 @@ const clientMetadataTokenExchangeFields = (...(clientMetadata?.os ? { client_os: clientMetadata.os } : {}),});+// The server reads these off the /ws upgrade URL next to wsTicket. Optional on+// both ends: old servers ignore unknown params, old clients never send them.+export const appendClientConnectionParams = (+ url: URL,+ clientMetadata: AuthClientPresentationMetadata | undefined,+): void => {+ if (clientMetadata?.surface) {+ url.searchParams.set("clientSurface", clientMetadata.surface);+ }+ if (clientMetadata?.appVersion) {+ url.searchParams.set("clientAppVersion", clientMetadata.appVersion);+ }+};+export const exchangeRemoteDpopAccessToken = Effect.fn("clientRuntime.authorization.exchangeRemoteDpopAccessToken",)(function* (input: {@@ -174,6 +188,7 @@ export const resolveRemoteWebSocketConnectionUrl = Effect.fn(readonly wsBaseUrl: string;readonly httpBaseUrl: string;readonly bearerToken: string;+ readonly clientMetadata?: AuthClientPresentationMetadata;readonly timeoutMs?: number;}) {const issued = yield* issueRemoteWebSocketTicket({@@ -187,6 +202,7 @@ export const resolveRemoteWebSocketConnectionUrl = Effect.fn(url.pathname = "/ws";}url.searchParams.set("wsTicket", issued.ticket);+ appendClientConnectionParams(url, input.clientMetadata);return url.toString();});@@ -197,6 +213,7 @@ export const resolveRemoteDpopWebSocketConnectionUrl = Effect.fn(readonly httpBaseUrl: string;readonly accessToken: string;readonly dpopProof: string;+ readonly clientMetadata?: AuthClientPresentationMetadata;readonly timeoutMs?: number;}) {const issued = yield* issueRemoteDpopWebSocketTicket({@@ -210,5 +227,6 @@ export const resolveRemoteDpopWebSocketConnectionUrl = Effect.fn(url.pathname = "/ws";}url.searchParams.set("wsTicket", issued.ticket);+ appendClientConnectionParams(url, input.clientMetadata);return url.toString();});diff --git a/packages/client-runtime/src/authorization/service.ts b/packages/client-runtime/src/authorization/service.tsindex 410c7a39d..fef8db274 100644--- a/packages/client-runtime/src/authorization/service.ts+++ b/packages/client-runtime/src/authorization/service.ts@@ -131,6 +131,7 @@ export const make = Effect.gen(function* () {wsBaseUrl: input.wsBaseUrl,httpBaseUrl: input.httpBaseUrl,bearerToken: input.bearerToken,+ clientMetadata: presentation.metadata,}).pipe(Effect.mapError(mapRemoteEnvironmentError),Effect.provideService(HttpClient.HttpClient, httpClient),@@ -170,6 +171,7 @@ export const make = Effect.gen(function* () {httpBaseUrl: token.endpoint.httpBaseUrl,accessToken: token.accessToken,dpopProof: ticketProof,+ clientMetadata: presentation.metadata,...(timeoutMs === undefined ? {} : { timeoutMs }),}).pipe(Effect.provideService(HttpClient.HttpClient, httpClient));},diff --git a/packages/client-runtime/src/connection/resolver.test.ts b/packages/client-runtime/src/connection/resolver.test.tsindex d0375e555..d71c0f960 100644--- a/packages/client-runtime/src/connection/resolver.test.ts+++ b/packages/client-runtime/src/connection/resolver.test.ts@@ -174,6 +174,13 @@ const makeDependencies = Effect.fn("TestConnectionResolver.makeDependencies")((obearerToken: Effect.succeed(Option.fromNullishOr(options?.primaryBearerToken)),}),),+ Layer.succeed(+ ClientCapabilities.ClientPresentation,+ ClientCapabilities.ClientPresentation.of({+ metadata: { label: "Test Client", deviceType: "desktop", surface: "web" },+ scopes: [],+ }),+ ),Layer.succeed(ClientCapabilities.RelayDeviceIdentity,ClientCapabilities.RelayDeviceIdentity.of({@@ -216,7 +223,7 @@ describe("ConnectionResolver", () => {environmentId: ENVIRONMENT_ID,label: "Primary",httpBaseUrl: "http://127.0.0.1:3777",- socketUrl: "ws://127.0.0.1:3777/ws",+ socketUrl: "ws://127.0.0.1:3777/ws?clientSurface=web",httpAuthorization: null,target,});diff --git a/packages/client-runtime/src/connection/resolver.ts b/packages/client-runtime/src/connection/resolver.tsindex c219bde09..3a5d5437a 100644--- a/packages/client-runtime/src/connection/resolver.ts+++ b/packages/client-runtime/src/connection/resolver.ts@@ -1,3 +1,4 @@+import type { AuthClientPresentationMetadata } from "@t3tools/contracts";import { RelayEnvironmentConnectScope } from "@t3tools/contracts/relay";import { withRelayClientTracing } from "@t3tools/shared/relayTracing";import * as Context from "effect/Context";@@ -6,6 +7,7 @@ import * as Layer from "effect/Layer";import * as Option from "effect/Option";import * as Schema from "effect/Schema";+import { appendClientConnectionParams } from "../authorization/remote.ts";import * as RemoteEnvironmentAuthorization from "../authorization/service.ts";import * as ManagedRelay from "../relay/managedRelay.ts";import * as ClientCapabilities from "../platform/capabilities.ts";@@ -46,16 +48,21 @@ const isBearerProfile = Schema.is(BearerConnectionProfile);const isSshProfile = Schema.is(SshConnectionProfile);const isBearerCredential = Schema.is(BearerConnectionCredential);-function primarySocketUrl(target: PrimaryConnectionTarget): string {+function primarySocketUrl(+ target: PrimaryConnectionTarget,+ clientMetadata: AuthClientPresentationMetadata | undefined,+): string {const url = new URL(target.wsBaseUrl);if (url.pathname === "" || url.pathname === "/") {url.pathname = "/ws";}+ appendClientConnectionParams(url, clientMetadata);return url.toString();}const makePrimaryBroker = Effect.fn("clientRuntime.connection.broker.makePrimary")(function* () {const auth = yield* ClientCapabilities.PrimaryEnvironmentAuth;+ const presentation = yield* ClientCapabilities.ClientPresentation;const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;return Effect.fn("clientRuntime.connection.broker.primary")(function* (@@ -67,7 +74,7 @@ const makePrimaryBroker = Effect.fn("clientRuntime.connection.broker.makePrimaryenvironmentId: target.environmentId,label: target.label,httpBaseUrl: target.httpBaseUrl,- socketUrl: primarySocketUrl(target),+ socketUrl: primarySocketUrl(target, presentation.metadata),httpAuthorization: null,target,} satisfies PreparedConnection;diff --git a/packages/contracts/src/auth.ts b/packages/contracts/src/auth.tsindex 70b289975..0af93dc03 100644--- a/packages/contracts/src/auth.ts+++ b/packages/contracts/src/auth.ts@@ -1,7 +1,7 @@import * as Schema from "effect/Schema";import * as HttpApiSchema from "effect/unstable/httpapi/HttpApiSchema";-import { AuthSessionId, TrimmedNonEmptyString } from "./baseSchemas.ts";+import { AuthSessionId, ClientSurface, TrimmedNonEmptyString } from "./baseSchemas.ts";/*** Declares the server's overall authentication posture.@@ -169,6 +169,8 @@ export const AuthClientPresentationMetadata = Schema.Struct({label: Schema.optionalKey(TrimmedNonEmptyString),deviceType: Schema.optionalKey(AuthClientMetadataDeviceType),os: Schema.optionalKey(TrimmedNonEmptyString),+ surface: Schema.optionalKey(ClientSurface),+ appVersion: Schema.optionalKey(TrimmedNonEmptyString),});export type AuthClientPresentationMetadata = typeof AuthClientPresentationMetadata.Type;diff --git a/packages/contracts/src/baseSchemas.ts b/packages/contracts/src/baseSchemas.tsindex 9a63f22c9..e12bf3e97 100644--- a/packages/contracts/src/baseSchemas.ts+++ b/packages/contracts/src/baseSchemas.ts@@ -71,6 +71,15 @@ export type AuthSessionId = typeof AuthSessionId.Type;export const RpcClientId = NonNegativeInt.pipe(Schema.brand("RpcClientId"));export type RpcClientId = typeof RpcClientId.Type;+/**+ * Which client app a connection comes from. Unlike+ * `AuthClientMetadataDeviceType` (a UA-style device class where web and+ * desktop are both "desktop"), this names the actual product surface.+ * Optional everywhere it appears: old clients never send it.+ */+export const ClientSurface = Schema.Literals(["web", "desktop", "mobile"]);+export type ClientSurface = typeof ClientSurface.Type;+export const ProviderItemId = makeEntityId("ProviderItemId");export type ProviderItemId = typeof ProviderItemId.Type;export const RuntimeSessionId = makeEntityId("RuntimeSessionId");diff --git a/packages/contracts/src/orchestration.ts b/packages/contracts/src/orchestration.tsindex c7c63270c..adb17879f 100644--- a/packages/contracts/src/orchestration.ts+++ b/packages/contracts/src/orchestration.ts@@ -8,6 +8,7 @@ import { RepositoryIdentity, ThreadEnvMode } from "./environment.ts";import {ApprovalRequestId,CheckpointRef,+ ClientSurface,CommandId,EventId,IsoDateTime,@@ -1319,12 +1320,25 @@ export const ThreadActivityAppendedPayload = Schema.Struct({activity: OrchestrationThreadActivity,});+/**+ * Which client connection dispatched the command that produced an event.+ * Stamped by the orchestration engine on client-dispatched commands; absent on+ * provider/server-originated events and on commands from clients too old to+ * report it.+ */+export const OrchestrationClientOrigin = Schema.Struct({+ surface: Schema.optional(ClientSurface),+ appVersion: Schema.optional(TrimmedNonEmptyString),+});+export type OrchestrationClientOrigin = typeof OrchestrationClientOrigin.Type;+export const OrchestrationEventMetadata = Schema.Struct({providerTurnId: Schema.optional(TrimmedNonEmptyString),providerItemId: Schema.optional(ProviderItemId),adapterKey: Schema.optional(TrimmedNonEmptyString),requestId: Schema.optional(ApprovalRequestId),ingestedAt: Schema.optional(IsoDateTime),+ origin: Schema.optional(OrchestrationClientOrigin),});export type OrchestrationEventMetadata = typeof OrchestrationEventMetadata.Type;