@devries-cameron20 / t3code-1 / commits / 3e9d97ae1f
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

feat(server): count how guest sharing gets used (#24996)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Theo Browne committed Oct 25, 2026 at 16:43 UTC 3e9d97ae1f7cd567376fed6dfc6c929f3bc881cb
6 files changed +99 -16
apps/server/src/guest/GuestShareService.test.ts
+35
@@ -13,6 +13,7 @@ import {
13 ThreadId,
14 TurnItemId,
15 } from "@t3tools/contracts";
16 +import * as Context from "effect/Context";
17 import * as DateTime from "effect/DateTime";
18 import type * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
19 import * as Effect from "effect/Effect";
@@ -47,6 +48,7 @@ import * as ResourceCleanupService from "../orchestration-v2/ResourceCleanupServ
48 import * as ProviderReplayHarness from "../orchestration-v2/testkit/ProviderReplayHarness.ts";
49 import * as ProviderRegistry from "../provider/ProviderRegistry.ts";
50 import * as ServerSettings from "../serverSettings.ts";
51 +import * as AnalyticsService from "../telemetry/AnalyticsService.ts";
52 import * as GuestShareService from "./GuestShareService.ts";
53
54 const instanceId = ProviderInstanceId.make("codex");
@@ -104,6 +106,26 @@ const layerCleanup = Layer.effect(
106 };
107 }),
108 ).pipe(Layer.provide(layerConfig), Layer.provide(NodeServices.layer));
109 +class RecordedAnalytics extends Context.Service<
110 + RecordedAnalytics,
111 + Ref.Ref<ReadonlyArray<Readonly<Record<string, unknown>>>>
112 +>()("t3/guest/GuestShareService.test/RecordedAnalytics") {}
113 +const layerAnalytics = Layer.effectContext(
114 + Effect.gen(function* () {
115 + const recorded = yield* Ref.make<ReadonlyArray<Readonly<Record<string, unknown>>>>([]);
116 + return Context.make(RecordedAnalytics, recorded).pipe(
117 + Context.add(
118 + AnalyticsService.AnalyticsService,
119 + AnalyticsService.AnalyticsService.of({
120 + record: (event, properties) =>
121 + Ref.update(recorded, (events) => [...events, { event, ...properties }]),
122 + flush: Effect.void,
123 + recordOwners: () => Effect.void,
124 + }),
125 + ),
126 + );
127 + }),
128 +);
129 const layerTest = GuestShareService.layer.pipe(
130 Layer.provideMerge(
131 CommandOutputHub.layer.pipe(
@@ -113,6 +135,7 @@ const layerTest = GuestShareService.layer.pipe(
135 Layer.provide(layerProviders),
136 Layer.provideMerge(ServerSettings.layerTest({ guestSharingEnabled: true })),
137 Layer.provide(layerConnect),
138 + Layer.provideMerge(layerAnalytics),
139 Layer.provide(ServerSecretStore.layer),
140 Layer.provideMerge(layerConfig),
141 Layer.provideMerge(NodeServices.layer),
@@ -172,6 +195,18 @@ it.effect("spends an invite once and ends the guest stream when the owner stops
195 }).pipe(Effect.provide(layerTest)),
196 );
197
198 +it.effect("counts a guest joining and sending, without their name or text", () =>
199 + Effect.gen(function* () {
200 + const { guestShares, credential } = yield* shareThread;
201 + const { token: session, shareId } = yield* guestShares.redeem({ credential, name: "Sam" });
202 + yield* guestShares.submit(session, { shareId, text: "Hello" }, []);
203 + assert.deepEqual(yield* Ref.get(yield* RecordedAnalytics), [
204 + { event: "feature.used", feature: "guest_share.join" },
205 + { event: "feature.used", feature: "guest_message.submit", variant: "text_only" },
206 + ]);
207 + }).pipe(Effect.provide(layerTest)),
208 +);
209 +
210 it.effect("streams the owner's thread events after the share and a snapshot", () =>
211 Effect.gen(function* () {
212 const { orchestrator, guestShares, credential } = yield* shareThread;
apps/server/src/guest/GuestShareService.ts
+8
@@ -58,6 +58,7 @@ import {
58 } from "../orchestration-v2/WireProjection.ts";
59 import * as ProviderRegistry from "../provider/ProviderRegistry.ts";
60 import * as ServerSettings from "../serverSettings.ts";
61 +import * as AnalyticsService from "../telemetry/AnalyticsService.ts";
62 import { guestShareView, guestThreadModel } from "./guestView.ts";
63 import {
64 classifyGuestUploads,
@@ -215,6 +216,7 @@ const make = Effect.gen(function* () {
216 const fileSystem = yield* FileSystem.FileSystem;
217 const crypto = yield* Crypto.Crypto;
218 const secretStore = yield* ServerSecretStore.ServerSecretStore;
219 + const analytics = yield* AnalyticsService.AnalyticsService;
220 const signingKey = yield* Effect.cached(
221 secretStore.getOrCreateRandom(SIGNING_SECRET_NAME, 32).pipe(Effect.orDie),
222 );
@@ -357,6 +359,8 @@ const make = Effect.gen(function* () {
359 shareId: share.id,
360 guestName: request.name,
361 });
362 + // Guests have no client connection, so their events carry no surface.
363 + yield* analytics.record("feature.used", { feature: "guest_share.join" });
364 const token = yield* signSession({ kind: "session", threadId: thread.id, shareId: share.id });
365 return { token, shareId: share.id };
366 });
@@ -447,6 +451,10 @@ const make = Effect.gen(function* () {
451 text: request.text,
452 ...(attachments.length === 0 ? {} : { attachments }),
453 }).pipe(Effect.onError(() => removeStored(attachments)));
454 + yield* analytics.record("feature.used", {
455 + feature: "guest_message.submit",
456 + variant: attachments.length === 0 ? "text_only" : "with_files",
457 + });
458 });
459
460 /** Completes once the session no longer opens its share, so open reads end with it. */
apps/server/src/telemetry/FeatureUsage.test.ts
+30
@@ -67,3 +67,33 @@ it("reads RPC variants from enums, never from paths or text", () => {
67 feature: "terminal.open",
68 });
69 });
70 +
71 +it("counts the owner's guest share actions, and only guest message sends", () => {
72 + const send = (guestMessageId?: string) =>
73 + commandFeatureUsage(
74 + command({
75 + ...ids,
76 + type: "message.dispatch",
77 + messageId: "message-private",
78 + text: "secret prompt",
79 + attachments: [],
80 + createdBy: "user",
81 + creationSource: "web",
82 + dispatchMode: { type: "start_immediately" },
83 + ...(guestMessageId === undefined ? {} : { guestMessageId }),
84 + }),
85 + );
86 + expect(send("guest-message-private")).toEqual({ feature: "guest_message.send" });
87 + expect(send()).toBe(undefined);
88 + expect(
89 + commandFeatureUsage(
90 + command({ ...ids, type: "thread.guest-message.dismiss", guestMessageId: "guest-private" }),
91 + ),
92 + ).toEqual({ feature: "guest_message.dismiss" });
93 + expect(commandFeatureUsage(command({ ...ids, type: "thread.guest-share.close" }))).toEqual({
94 + feature: "guest_share.close",
95 + });
96 + expect(featureUsage(WS_METHODS.guestShareCreate, { threadId: "thread-private" })).toEqual({
97 + feature: "guest_share.create",
98 + });
99 +});
apps/server/src/telemetry/FeatureUsage.ts
+9 -4
@@ -14,14 +14,16 @@ const use = (feature: string, variant?: string): FeatureUsage =>
14 variant === undefined ? { feature } : { feature, variant };
15
16 /**
17 - * Exclude housekeeping and `message.dispatch`, which `client.turn.requested` already counts.
18 - * Record at command dispatch so retries that commit no change do not count twice.
17 + * Exclude housekeeping. `client.turn.requested` counts every `message.dispatch`; only sending a
18 + * guest's message is also a feature. Record at command dispatch so retries do not count twice.
19 */
20 const COMMAND_FEATURES: {
21 readonly [Type in OrchestrationV2Command["type"]]?: (
22 command: Extract<OrchestrationV2Command, { readonly type: Type }>,
23 - ) => FeatureUsage;
23 + ) => FeatureUsage | undefined;
24 } = {
25 + "message.dispatch": (command) =>
26 + command.guestMessageId === undefined ? undefined : { feature: "guest_message.send" },
27 "checkpoint.rollback": (command) => ({
28 feature: "checkpoint.rollback",
29 variant: command.restoreFiles === false ? "conversation_only" : "with_files",
@@ -42,6 +44,8 @@ const COMMAND_FEATURES: {
44 "run.interrupt": () => ({ feature: "run.interrupt" }),
45 "queued-message.promote-to-steer": () => ({ feature: "queue.steer" }),
46 "queued-run.edit": () => ({ feature: "queue.edit" }),
47 + "thread.guest-share.close": () => ({ feature: "guest_share.close" }),
48 + "thread.guest-message.dismiss": () => ({ feature: "guest_message.dismiss" }),
49 };
50
51 /**
@@ -67,13 +71,14 @@ const METHOD_FEATURES: Readonly<Record<string, (payload: Payload) => FeatureUsag
71 [WS_METHODS.projectCloneStart]: () => ({ feature: "project.clone" }),
72 [WS_METHODS.sourceControlPublishRepository]: () => ({ feature: "repository.publish" }),
73 [WS_METHODS.serverUpsertKeybinding]: () => ({ feature: "keybinding.customize" }),
74 + [WS_METHODS.guestShareCreate]: () => ({ feature: "guest_share.create" }),
75 };
76
77 /** The feature a dispatched command uses, or undefined when it is not a tracked feature. */
78 export function commandFeatureUsage(command: OrchestrationV2Command): FeatureUsage | undefined {
79 // TypeScript cannot pair a union's tag with its own entry, so widen once here.
80 const mapping = COMMAND_FEATURES[command.type] as
76 - | ((command: OrchestrationV2Command) => FeatureUsage)
81 + | ((command: OrchestrationV2Command) => FeatureUsage | undefined)
82 | undefined;
83 return mapping?.(command);
84 }
apps/server/src/ws.ts
+14 -11
@@ -1262,18 +1262,21 @@ export const layerWsRpc = (
1262 const analytics = yield* AnalyticsService.AnalyticsService;
1263 const originProps = clientAnalyticsProps;
1264 const recordClientCommandAnalytics = (command: OrchestrationV2Command) => {
1265 - if (command.type === "message.dispatch") {
1266 - return analytics.record("client.turn.requested", originProps).pipe(Effect.ignore);
1267 - }
1265 const usage = commandFeatureUsage(command);
1269 - return usage === undefined
1270 - ? Effect.void
1271 - : analytics
1272 - .record("feature.used", {
1273 - ...usage,
1274 - ...(originProps.surface === undefined ? {} : { surface: originProps.surface }),
1275 - })
1276 - .pipe(Effect.ignore);
1266 + return Effect.all(
1267 + [
1268 + command.type === "message.dispatch"
1269 + ? analytics.record("client.turn.requested", originProps)
1270 + : Effect.void,
1271 + usage === undefined
1272 + ? Effect.void
1273 + : analytics.record("feature.used", {
1274 + ...usage,
1275 + ...(originProps.surface === undefined ? {} : { surface: originProps.surface }),
1276 + }),
1277 + ],
1278 + { discard: true },
1279 + ).pipe(Effect.ignore);
1280 };
1281 const threadLaunch = yield* ThreadLaunchService.ThreadLaunchService;
1282 const commandOutputHub = yield* CommandOutputHub.CommandOutputHub;
docs/internals/product-analytics.md
+3 -1
@@ -75,7 +75,9 @@ the RPC authorization middleware after the request succeeds; dispatched commands
75 are recorded by the dispatch handler, which can tell a retry apart.
76 [Feature mapping](../../apps/server/src/telemetry/FeatureUsage.ts) allowlists
77 the methods and commands, and takes variants only from closed contract enums,
78 -so paths, ids, and text never reach analytics.
78 +so paths, ids, and text never reach analytics. Guests of a shared thread have no
79 +WebSocket connection, so the guest share service records their joins and messages
80 +itself, with no `surface`.
81
82 Agent tool events report driver kinds, never instance ids: users name
83 instances, so an instance id can identify an account or employer.