Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
feat(console): extend telemetry to the remaining user events (CHOO-2285) (#280)
Christian McDermottd7964885d00a
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 83d84b1c5..08fcd1094 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -771,6 +771,46 @@ version of their own to them without also giving them a release of their own.## switch-console### [Unreleased]+#### Added+- Creating an agent, starting a session and adding a server now report whether+ they worked, and an enumerated reason when they did not. Previously only the+ ones that succeeded were counted, so nothing showed where people got stuck.+ A session start also records which button it came from, whether a room and an+ opening prompt were chosen, and whether a person started the session, the app+ started it on their behalf, or it was found already running on a remote host —+ never the room, the prompt or the host.+- Removing an agent, resetting a remote agent, removing a server, attaching a+ remote session's terminal and retrying a session that failed to set up are all+ reported now, each with whether it worked. Removing an agent distinguishes a+ person doing it from a server teardown sweeping every agent up with it.+- Installing, updating and removing an agent's CLI is reported — the app's main+ first-run wall, and previously invisible. So are creating and deleting rooms,+ signing in and out, connecting and disconnecting a messaging app, setting up a+ remote host, starting and stopping a managed server, and the update check,+ download and install.+- Where people stop is now visible: the first-run checklist, the add-a-server+ wizard, which screens get opened and which commands get run. Opening a link+ from a message reports whether this copy of the app could find what the link+ pointed at.+- Turning usage sharing **on** is reported. Turning it off is not, and cannot+ be: the check happens immediately before anything is sent, so the moment+ someone declines is the moment nothing more is sent. The opt-out rate stays+ unknown rather than being obtained that way.++#### Fixed+- Retrying a session that failed to set up now says whether it worked. The retry+ reported failure by throwing, which nothing was listening for, so a second+ attempt that failed left the session sitting on "setting up" with no error and+ no explanation.+- Deleting an agent left its sessions counted as still running. The sessions were+ removed by the database itself, so nothing in the app was told they had ended.+- A session that is un-archived can end again. Its first ending was remembered+ for good, so the second one — and every one after it — went unrecorded.+- A remote agent whose host refuses the connection now says so, rather than+ reporting the generic failure every other fault shares.+- Installing an update no longer reports that it both worked and failed. The+ success was sent before handing over to the installer, so an install that then+ failed to take was counted twice, in both directions.### [0.30.0] - 2026-08-24diff --git a/console/AGENTS.md b/console/AGENTS.mdindex 25f87659e..86c148783 100644--- a/console/AGENTS.md+++ b/console/AGENTS.md@@ -417,9 +417,11 @@ pnpm run lintFlipping the default back to on is a product decision that requires the id to go first,not a code change.- **What a telemetry payload may contain.** Add an event only by adding it to the closed- catalogue in `src/main/core/telemetry/events.ts`: its property types are literal unions- and numbers, and `TELEMETRY_EVENT_PROPERTIES` names the same fields as data, which the- emitter uses to drop anything else before it builds a payload. The types alone are not+ catalogue in `src/main/core/telemetry/events.ts`: its property types are literal unions,+ numbers and booleans, and `TELEMETRY_EVENT_PROPERTIES` names the same fields as data, which+ the emitter uses to drop anything else before it builds a payload. A count goes as a number+ and a yes/no as a boolean rather than as text, so both stay usable at the far end; anything+ else — an object, an array, `null`, a non-finite number — is refused rather than encoded. The types alone are notenough — excess-property checking does not apply through a spread — so the runtimefilter is what makes "nothing free-text can reach a payload" true rather than intended.Permitted: which of the catalogued things happened, agent type, local-vs-remote,@@ -429,10 +431,47 @@ pnpm run lintagent, room, project, location or server names or ids. Widening this is a consentdecision — the user-facing wording lives in`src/renderer/features/telemetry/telemetry-copy.ts` and must be kept in step with it.+- **The interface may report only through the one gate.** Almost everything is+ reported from the main process, where a call site is type-checked against the+ catalogue. The exceptions are moments that exist only in the UI — a screen+ opened, a command run, a checklist abandoned — and they go through+ `rpc.telemetry.track` into `src/main/core/telemetry/renderer-events.ts`, which+ checks the event is one of the few permitted and every value against the set+ the catalogue allows. That check is not ceremony: a type does not survive a+ process boundary, so it is the only thing standing between a received value+ and a payload. Do not add a second path, and if a moment can be observed from+ the main process, observe it there.+- **Report a moment, not a state — and if you must report a state, claim it after+ the gate.** A condition that is true from the instant it becomes true is true+ again on every later launch, so reporting it directly counts it forever;+ `ONCE_PER_INSTALL` in `renderer-events.ts` exists for that case and keeps the+ record beside the emitter rather than in the user's settings, which would+ report a setting nobody changed. The record is spent once and never given+ back, so it must not be claimed until a send is actually possible: the app+ renders behind the first-run consent prompt, so anything claiming before the+ consent check spends its one chance while the answer is still unset and+ retires the event for the life of the install.+- **Prefer a value the caller declares to one you read back.** Several+ dimensions describe an intent that only the caller has — which button, which+ source, whether a room was chosen — and the state that would answer is often+ consumed by the very operation being reported. Pass it through the params;+ narrow it at the emitter, because it crossed a process boundary.+- **A fallback must not assert something.** `unknown` is the right default for a+ dimension nobody supplied. Falling back to a real variant — `user` for "who+ started this" — reports a claim the code has no evidence for, and it lands in+ the bucket a human would read as deliberate.- **Telemetry never affects the user.** It is fire-and-forget with a short timeout and noretry: a send that fails is logged with an `errorCode` and dropped. It must never block,delay or fail an operation, and must never surface in the UI. It is off in a dev build,which is logged once so a build that is not reporting says why.+- **The compile-time guards are load-bearing; keep them in the `[X] extends+ [never]` form.** An indexed access by a union distributes and then collapses,+ so `Map[Union]` yields `true | never` — which is `true`, and passes while+ every member but one is wrong. Two assertions in this area were written that+ way and asserted nothing. Wrapping both sides in a tuple stops the+ distribution. Note also that `satisfies { [K in Name]: readonly (keyof T[K])[] }`+ constrains what an array *may* contain, never what it *must* — that is why+ `_everyPropertyIsAllowListed` is a separate check.- **The sidecar sends nothing.** It runs headless on a user's VM with no consent promptand no access to this setting, so sessions it starts are not counted. Do not "fix" thatby having it report; the gate is not reachable from there.diff --git a/console/apps/switch-console-desktop/src/main/app/deeplinks.ts b/console/apps/switch-console-desktop/src/main/app/deeplinks.tsindex df33a21c1..76888c31b 100644--- a/console/apps/switch-console-desktop/src/main/app/deeplinks.ts+++ b/console/apps/switch-console-desktop/src/main/app/deeplinks.ts@@ -77,8 +77,9 @@ export function handleDeeplinkUrl(rawUrl: string): void {focusWindow();const win = getMainWindow();if (win && !win.webContents.isLoading()) {- events.emit(sessionDeeplinkChannel, parsed);+ events.emit(sessionDeeplinkChannel, { ...parsed, coldStart: false });} else {+ // Buffered because there is no window yet — which is what a cold start is.pending = parsed;}}@@ -86,7 +87,7 @@ export function handleDeeplinkUrl(rawUrl: string): void {/** Emit any deeplink buffered during a cold start, once the window has loaded. */export function flushPendingDeeplink(): void {if (pending === null) return;- events.emit(sessionDeeplinkChannel, pending);+ events.emit(sessionDeeplinkChannel, { ...pending, coldStart: true });pending = null;}diff --git a/console/apps/switch-console-desktop/src/main/core/agents/add-agent.test.ts b/console/apps/switch-console-desktop/src/main/core/agents/add-agent.test.tsindex 9ab263d21..28740a178 100644--- a/console/apps/switch-console-desktop/src/main/core/agents/add-agent.test.ts+++ b/console/apps/switch-console-desktop/src/main/core/agents/add-agent.test.ts@@ -86,9 +86,11 @@ vi.mock('./setAgentAutoSession', () => ({reconcileAgentAutoSessionFromGateway: vi.fn(async () => {}),}));vi.mock('./agent-events', () => ({ agentEvents: { _emit: vi.fn() } }));+vi.mock('@main/core/telemetry/telemetry-service', () => ({ trackEvent: vi.fn() }));vi.mock('@main/lib/logger', () => ({ log: { info: vi.fn(), warn: vi.fn(), error: vi.fn() } }));const { addAgent } = await import('./add-agent');+const { trackEvent } = await import('@main/core/telemetry/telemetry-service');function params(overrides: Record<string, unknown> = {}) {return {@@ -103,6 +105,7 @@ function params(overrides: Record<string, unknown> = {}) {autoApprove: false,instructions: '',definitionAttributes: {},+ entryPoint: 'unknown' as const,...overrides,};}@@ -228,4 +231,100 @@ describe('addAgent', () => {expect(h.registerAgentIdentity).not.toHaveBeenCalled();expect(h.createAgent).not.toHaveBeenCalled();});++ describe('what it reports', () => {+ beforeEach(() => {+ vi.mocked(trackEvent).mockClear();+ });++ it('reports a creation that failed, with the reason as a code', async () => {+ // The success is reported from the `agent:created` hook, which by+ // definition never fires here — so without this the entire failure+ // population is missing rather than merely unexplained.+ h.registerAgentIdentity.mockResolvedValue({ kind: 'unauthenticated' } as never);++ await addAgent(params({ entryPoint: 'command_palette' }));++ expect(trackEvent).toHaveBeenCalledWith('agent_created', {+ agent_type: 'codex',+ location: 'local',+ outcome: 'failure',+ failure_reason: 'unauthenticated',+ entry_point: 'command_palette',+ });+ });++ it('reports a refusal that happens before anything is minted', async () => {+ h.state.nameTaken = true;++ await addAgent(params({ entryPoint: 'sidebar' }));++ expect(trackEvent).toHaveBeenCalledWith(+ 'agent_created',+ expect.objectContaining({ outcome: 'failure', failure_reason: 'name_conflict' })+ );+ });++ it('describes a remote failure as remote, from what was asked for', async () => {+ // There is no row to read the location from — the agent was never+ // created. The parameters are the only account of what was attempted.+ h.registerAgentIdentity.mockResolvedValue({ kind: 'unauthenticated' } as never);++ await addAgent(params({ sshHost: 'build-box', entryPoint: 'server_page' }));++ expect(trackEvent).toHaveBeenCalledWith(+ 'agent_created',+ expect.objectContaining({ location: 'remote' })+ );+ });++ it('reports a failure that arrives as a throw, after the identity was minted', async () => {+ // The worst case this function has: the identity exists on the gateway and+ // nothing here points at it. Without this, the one population that leaves+ // an orphan behind is the one nothing counts.+ h.createAgent.mockRejectedValueOnce(new Error('UNIQUE constraint failed'));++ await expect(addAgent(params({ entryPoint: 'agent_page' }))).rejects.toThrow(+ 'UNIQUE constraint failed'+ );++ expect(trackEvent).toHaveBeenCalledWith('agent_created', {+ agent_type: 'codex',+ location: 'local',+ outcome: 'failure',+ failure_reason: 'error',+ entry_point: 'agent_page',+ });+ });++ it('reports a throw once, and never its message', async () => {+ h.registerAgentIdentity.mockRejectedValueOnce(+ new Error('/Users/someone/secret-project could not be registered')+ );++ await expect(addAgent(params())).rejects.toThrow();++ expect(vi.mocked(trackEvent).mock.calls).toHaveLength(1);+ expect(JSON.stringify(vi.mocked(trackEvent).mock.calls)).not.toContain('secret-project');+ });++ it('reports nothing itself when the agent is created', async () => {+ // Reporting here as well as from the hook would double-count every+ // successful creation.+ await addAgent(params());++ expect(trackEvent).not.toHaveBeenCalled();+ });++ it('never puts the failure message in the payload', async () => {+ h.registerAgentIdentity.mockResolvedValue({+ kind: 'error',+ message: '/Users/someone/secret-project is not writable',+ } as never);++ await addAgent(params());++ expect(JSON.stringify(vi.mocked(trackEvent).mock.calls)).not.toContain('secret-project');+ });+ });});diff --git a/console/apps/switch-console-desktop/src/main/core/agents/add-agent.ts b/console/apps/switch-console-desktop/src/main/core/agents/add-agent.tsindex b7c69ea74..dc7288902 100644--- a/console/apps/switch-console-desktop/src/main/core/agents/add-agent.ts+++ b/console/apps/switch-console-desktop/src/main/core/agents/add-agent.ts@@ -5,11 +5,16 @@ import { checkIsValidDirectory } from '@main/core/locations/path-utils';import { ensureLocation, getLocationByHostDir } from '@main/core/locations/store';import { getPlugin } from '@main/core/providers/plugin-registry';import { getServer } from '@main/core/switch-servers/servers-store';+import { agentTypeOf } from '@main/core/telemetry/agent-type';+import type { TelemetryAgentCreateFailure } from '@main/core/telemetry/events';+import { entryPointOf } from '@main/core/telemetry/narrow';+import { trackEvent } from '@main/core/telemetry/telemetry-service';import { log } from '@main/lib/logger';import { agentAvatarUrlForName } from '@shared/core/agents/agent-avatar';import type { AgentProviderConfig } from '@shared/core/agents/agent-provider-config';import type { Agent } from '@shared/core/agents/agents';import type { AgentProviderId } from '@shared/core/providers/agent-provider-registry';+import type { UiEntryPoint } from '@shared/core/telemetry/reporting';import { basenameFromAnyPath } from '@shared/path-name';import { writeAgentConfigFile } from './agent-config-file';import { syncAgentConfig } from './agent-config-sync';@@ -55,6 +60,8 @@ export type AddAgentParams = {* effort / instructions). Distinct from `definitionAttributes`, which is the* repo-agent definition surface Codex does not use. */providerConfig?: AgentProviderConfig | null;+ /** Which control the user opened the add-agent form from, for reporting. */+ entryPoint: UiEntryPoint;};export type AddAgentResult =@@ -65,6 +72,43 @@ export type AddAgentResult =| { kind: 'invalid-name'; message: string }| { kind: 'error'; message: string };+/** The result's discriminant as a reportable code. Never its message. */+const ADD_AGENT_FAILURE_REASON: Record<+ Exclude<AddAgentResult['kind'], 'created'>,+ TelemetryAgentCreateFailure+> = {+ unauthenticated: 'unauthenticated',+ 'name-conflict': 'name_conflict',+ 'credentials-conflict': 'credentials_conflict',+ 'invalid-name': 'invalid_name',+ error: 'error',+};++/**+ * Report a creation that did not happen.+ *+ * Reported here rather than from the `agent:created` hook, which by definition+ * only fires when one succeeded. The location is read from the parameters, not+ * the database: no row exists to look it up from, and the parameters are what+ * the user asked for.+ */+function reportCreateFailure(params: AddAgentParams, reason: TelemetryAgentCreateFailure): void {+ trackEvent('agent_created', {+ agent_type: agentTypeOf(params.providerId),+ location: params.sshHost === null ? 'local' : 'remote',+ outcome: 'failure',+ failure_reason: reason,+ entry_point: entryPointOf(params.entryPoint),+ });+}++/** The same, wrapped around a failing return so it can stay an expression. */+function reportFailedCreate(params: AddAgentParams, result: AddAgentResult): AddAgentResult {+ if (result.kind === 'created') return result;+ reportCreateFailure(params, ADD_AGENT_FAILURE_REASON[result.kind]);+ return result;+}+/*** Add a new agent to a location: mint its Switch identity on the gateway, write* its provider definition (`.claude/agents/<name>.md`) and its per-agent Switch@@ -79,19 +123,41 @@ export type AddAgentResult =* throws (leaving the gateway agent, as the pre-existing provision path did).*/export async function addAgent(params: AddAgentParams): Promise<AddAgentResult> {+ try {+ return await runAddAgent(params);+ } catch (error) {+ // The half of the failures that are not a typed return, and the half worth+ // watching most: everything past the identity mint signals failure by+ // throwing, and those are the attempts that leave an agent registered on the+ // gateway with nothing here pointing at it. `error` is the only honest code+ // — these are not a named union, and their messages carry paths.+ reportCreateFailure(params, 'error');+ throw error;+ }+}++async function runAddAgent(params: AddAgentParams): Promise<AddAgentResult> {if (params.sshHost === null && !checkIsValidDirectory(params.dir)) {- return { kind: 'error', message: `Invalid directory: ${params.dir}` };+ return reportFailedCreate(params, {+ kind: 'error',+ message: `Invalid directory: ${params.dir}`,+ });}const server = await getServer(params.serverId);- if (!server) return { kind: 'error', message: `No Switch server with id ${params.serverId}` };+ if (!server) {+ return reportFailedCreate(params, {+ kind: 'error',+ message: `No Switch server with id ${params.serverId}`,+ });+ }// Before minting an identity: the gateway's uniqueness check is scoped to the// Switch server, so it cannot see a name already taken in this directory. Two// same-named agents here would share one `.switch/agents/<name>.json`.const existingLocation = await getLocationByHostDir(params.sshHost, params.dir);if (existingLocation && (await agentNameTaken(existingLocation.id, params.name, null))) {- return { kind: 'name-conflict' };+ return reportFailedCreate(params, { kind: 'name-conflict' });}// And the check above only sees agents THIS install manages. A second Switch@@ -106,7 +172,12 @@ export async function addAgent(params: AddAgentParams): Promise<AddAgentResult>params.name,server.apiUrl);- if (foreignEndpoint !== null) return { kind: 'credentials-conflict', endpoint: foreignEndpoint };+ if (foreignEndpoint !== null) {+ return reportFailedCreate(params, {+ kind: 'credentials-conflict',+ endpoint: foreignEndpoint,+ });+ }const registered = await registerAgentIdentity(server, {name: params.name,@@ -116,7 +187,7 @@ export async function addAgent(params: AddAgentParams): Promise<AddAgentResult>agentType: knownAgentTypeForProvider(params.providerId),iconUrl: params.iconUrl ?? agentAvatarUrlForName(params.name),});- if (registered.kind !== 'created') return registered;+ if (registered.kind !== 'created') return reportFailedCreate(params, registered);const behavior = getPlugin(params.providerId).behavior.repoAgents;const workspace = await resolveWorkspaceFsFor(params.sshHost, params.dir);@@ -177,6 +248,6 @@ export async function addAgent(params: AddAgentParams): Promise<AddAgentResult>});await locationManager.openLocation(location);- agentEvents._emit('agent:created', agent);+ agentEvents._emit('agent:created', agent, params.entryPoint);return { kind: 'created', agent };}diff --git a/console/apps/switch-console-desktop/src/main/core/agents/agent-events.ts b/console/apps/switch-console-desktop/src/main/core/agents/agent-events.tsindex 50f6389d8..f6ea8c3b2 100644--- a/console/apps/switch-console-desktop/src/main/core/agents/agent-events.ts+++ b/console/apps/switch-console-desktop/src/main/core/agents/agent-events.ts@@ -1,9 +1,14 @@import { HookCore, type Hookable } from '@main/lib/hookable';import { log } from '@main/lib/logger';import type { Agent } from '@shared/core/agents/agents';+import type { UiEntryPoint } from '@shared/core/telemetry/reporting';export type AgentCrudHooks = {- 'agent:created': (agent: Agent) => void | Promise<void>;+ /**+ * `entryPoint` is where the user started from, for reporting. Creators with+ * no user behind them pass `'unknown'` rather than inventing one.+ */+ 'agent:created': (agent: Agent, entryPoint: UiEntryPoint) => void | Promise<void>;'agent:updated': (agent: Agent) => void | Promise<void>;'agent:deleted': (agentId: string) => void | Promise<void>;};diff --git a/console/apps/switch-console-desktop/src/main/core/agents/attach-configured-agents.ts b/console/apps/switch-console-desktop/src/main/core/agents/attach-configured-agents.tsindex a04f32ba9..f232387c2 100644--- a/console/apps/switch-console-desktop/src/main/core/agents/attach-configured-agents.ts+++ b/console/apps/switch-console-desktop/src/main/core/agents/attach-configured-agents.ts@@ -171,6 +171,9 @@ export async function attachConfiguredAgents(}await locationManager.openLocation(location);- for (const agent of created) agentEvents._emit('agent:created', agent);+ // No control to name: an attach is driven by whichever screen offered the+ // scan, and nothing on the way here says which. `unknown` reports the absence+ // of a claim rather than inventing one.+ for (const agent of created) agentEvents._emit('agent:created', agent, 'unknown');return ok(created);}diff --git a/console/apps/switch-console-desktop/src/main/core/agents/controller.ts b/console/apps/switch-console-desktop/src/main/core/agents/controller.tsindex 770f8f667..39ec76ee3 100644--- a/console/apps/switch-console-desktop/src/main/core/agents/controller.ts+++ b/console/apps/switch-console-desktop/src/main/core/agents/controller.ts@@ -90,7 +90,10 @@ export const agentsController = createRPCController({getAgentById: (agentId: string) => getAgentById(agentId),renameAgent: (params: RenameAgentParams) => renameAgent(params),deleteAgent: (params: { agentId: string } & DeleteAgentOptions) =>- deleteAgent(params.agentId, { deleteInSwitch: params.deleteInSwitch }),+ deleteAgent(params.agentId, {+ deleteInSwitch: params.deleteInSwitch,+ trigger: params.trigger,+ }),resetRemoteAgent: (params: { agentId: string }) => resetRemoteAgent(params.agentId),updateAgent: (params: UpdateAgentParams) => updateAgent(params),assignServer: (params: { agentId: string; serverId: string }): Promise<AgentVerifyResult> =>diff --git a/console/apps/switch-console-desktop/src/main/core/agents/deleteAgent.test.ts b/console/apps/switch-console-desktop/src/main/core/agents/deleteAgent.test.tsindex eda2b7963..3780b49c8 100644--- a/console/apps/switch-console-desktop/src/main/core/agents/deleteAgent.test.ts+++ b/console/apps/switch-console-desktop/src/main/core/agents/deleteAgent.test.ts@@ -17,13 +17,24 @@ const h = vi.hoisted(() => {const removeLocal = vi.fn(async (fs: PluginFs, name: string) => {await fs.delete(`.claude/agents/${name}.md`);});- const state: { fs: PluginFs; repoAgents: object | null; agent: Record<string, unknown> | null } =- {- fs: fakeFs(),- repoAgents: { removeLocal },- agent: null,- };- return { state, removeLocal, removeSwitchCredentials: vi.fn(async () => {}) };+ const state: {+ fs: PluginFs;+ repoAgents: object | null;+ agent: Record<string, unknown> | null;+ sessionRows: { id: string }[];+ } = {+ fs: fakeFs(),+ repoAgents: { removeLocal },+ agent: null,+ sessionRows: [],+ };+ return {+ state,+ removeLocal,+ removeSwitchCredentials: vi.fn(async () => {}),+ sessionHookEmit: vi.fn(),+ trackEvent: vi.fn(),+ };});vi.mock('@main/core/providers/plugin-registry', () => ({@@ -52,7 +63,18 @@ vi.mock('@main/core/switch-rooms/auto-session-store', () => ({vi.mock('@main/core/switch-rooms/auto-session-watcher', () => ({autoSessionWatcher: { stopForAgent: vi.fn() },}));-vi.mock('@main/core/switch-servers/gateway-client', () => ({ deleteAgent: vi.fn() }));+vi.mock('@main/core/switch-servers/gateway-client', () => ({+ deleteAgent: vi.fn(),+ // The real class, because the reported failure code is read off it.+ GatewayError: class GatewayError extends Error {+ constructor(+ readonly kind: string,+ message: string+ ) {+ super(message);+ }+ },+}));vi.mock('@main/core/switch-servers/servers-store', () => ({ getServer: vi.fn() }));vi.mock('@main/core/view-state/view-state-service', () => ({viewStateService: { del: vi.fn(async () => {}) },@@ -64,10 +86,15 @@ vi.mock('@main/lib/logger', () => ({ log: { info: vi.fn(), warn: vi.fn(), error:vi.mock('@main/db/schema', () => ({ agents: {}, sessions: {} }));vi.mock('@main/db/client', () => ({db: {- select: () => ({ from: () => ({ where: async () => [] }) }),+ select: () => ({ from: () => ({ where: async () => h.state.sessionRows }) }),delete: () => ({ where: async () => undefined }),+ update: () => ({ set: () => ({ where: async () => undefined }) }),},}));+vi.mock('@main/core/sessions/session-hooks', () => ({+ sessionHooks: { _emit: h.sessionHookEmit },+}));+vi.mock('@main/core/telemetry/telemetry-service', () => ({ trackEvent: h.trackEvent }));const { deleteAgent } = await import('./deleteAgent');@@ -80,6 +107,7 @@ describe('deleteAgent', () => {vi.clearAllMocks();h.state.repoAgents = { removeLocal: h.removeLocal };h.state.agent = { id: 'agent-1', name: 'cc-hoot', providerId: 'claude', locationId: 'loc' };+ h.state.sessionRows = [];});it('removes the per-agent credentials for a provider with no repo-agent definitions', async () => {@@ -91,7 +119,7 @@ describe('deleteAgent', () => {const fs = fakeFs({ [agentSettingsRelativePath('codex-hoot')]: CREDS });h.state.fs = fs;- await deleteAgent('agent-1', { deleteInSwitch: false });+ await deleteAgent('agent-1', { deleteInSwitch: false, trigger: 'user' });expect(await fs.exists(agentSettingsRelativePath('codex-hoot'))).toBe(false);});@@ -103,7 +131,7 @@ describe('deleteAgent', () => {});h.state.fs = fs;- await deleteAgent('agent-1', { deleteInSwitch: false });+ await deleteAgent('agent-1', { deleteInSwitch: false, trigger: 'user' });expect(await fs.exists(agentSettingsRelativePath('cc-hoot'))).toBe(false);expect(await fs.exists('.claude/agents/cc-hoot.md')).toBe(false);@@ -116,8 +144,90 @@ describe('deleteAgent', () => {});h.state.fs = fs;- await deleteAgent('agent-1', { deleteInSwitch: false });+ await deleteAgent('agent-1', { deleteInSwitch: false, trigger: 'user' });expect(await fs.exists(agentSettingsRelativePath('cc-sibling'))).toBe(true);});++ describe('what it reports', () => {+ it('describes the agent that was removed, from the row before it goes', async () => {+ await deleteAgent('agent-1', { deleteInSwitch: false, trigger: 'user' });++ expect(h.trackEvent).toHaveBeenCalledWith('agent_removed', {+ agent_type: 'claude',+ location: 'local',+ delete_in_switch: false,+ trigger: 'user',+ outcome: 'success',+ failure_reason: 'none',+ });+ });++ it('separates a server teardown from a person removing an agent', async () => {+ // Wiping a managed server deletes every agent on it through this same+ // function; without the distinction one click looks like an exodus.+ await deleteAgent('agent-1', { deleteInSwitch: false, trigger: 'server_teardown' });++ expect(h.trackEvent).toHaveBeenCalledWith(+ 'agent_removed',+ expect.objectContaining({ trigger: 'server_teardown' })+ );+ });++ it('announces the sessions that went with it, which the database removes silently', async () => {+ // The rows go by a foreign key, so nothing else says they ended — and+ // every one of them reported starting.+ h.state.sessionRows = [{ id: 's-1' }, { id: 's-2' }];++ await deleteAgent('agent-1', { deleteInSwitch: false, trigger: 'user' });++ expect(h.sessionHookEmit).toHaveBeenCalledWith('session:deleted', 's-1');+ expect(h.sessionHookEmit).toHaveBeenCalledWith('session:deleted', 's-2');+ });++ it('reports the removal as failed, with a code, when the gateway refuses', async () => {+ const { deleteAgent: gatewayDeleteAgent } =+ await import('@main/core/switch-servers/gateway-client');+ vi.mocked(gatewayDeleteAgent).mockRejectedValue(new Error('boom'));+ h.state.agent = {+ id: 'agent-1',+ name: 'cc-hoot',+ providerId: 'claude',+ locationId: 'loc',+ serverId: 'srv-1',+ switchAgentId: 'sw-1',+ };+ const { getServer } = await import('@main/core/switch-servers/servers-store');+ vi.mocked(getServer).mockResolvedValue({ id: 'srv-1' } as never);++ await expect(+ deleteAgent('agent-1', { deleteInSwitch: true, trigger: 'user' })+ ).rejects.toThrow();++ expect(h.trackEvent).toHaveBeenCalledWith(+ 'agent_removed',+ expect.objectContaining({ outcome: 'failure', failure_reason: 'error' })+ );+ });++ it('reports an agent with no identity to delete as exactly that', async () => {+ h.state.agent = {+ id: 'agent-1',+ name: 'cc-hoot',+ providerId: 'claude',+ locationId: 'loc',+ serverId: null,+ switchAgentId: null,+ };++ await expect(+ deleteAgent('agent-1', { deleteInSwitch: true, trigger: 'user' })+ ).rejects.toThrow();++ expect(h.trackEvent).toHaveBeenCalledWith(+ 'agent_removed',+ expect.objectContaining({ failure_reason: 'not_linked_to_switch' })+ );+ });+ });});diff --git a/console/apps/switch-console-desktop/src/main/core/agents/deleteAgent.ts b/console/apps/switch-console-desktop/src/main/core/agents/deleteAgent.tsindex cf1e43b0e..cfa87aab4 100644--- a/console/apps/switch-console-desktop/src/main/core/agents/deleteAgent.ts+++ b/console/apps/switch-console-desktop/src/main/core/agents/deleteAgent.ts@@ -4,10 +4,22 @@ import {killSidecarSession,} from '@main/core/agent-runtime/impl/remote-sidecar-launcher';import { getPlugin } from '@main/core/providers/plugin-registry';+import { sessionHooks } from '@main/core/sessions/session-hooks';import { setAutoSessionAgent } from '@main/core/switch-rooms/auto-session-store';import { autoSessionWatcher } from '@main/core/switch-rooms/auto-session-watcher';-import { deleteAgent as gatewayDeleteAgent } from '@main/core/switch-servers/gateway-client';+import {+ deleteAgent as gatewayDeleteAgent,+ GatewayError,+} from '@main/core/switch-servers/gateway-client';import { getServer } from '@main/core/switch-servers/servers-store';+import { agentTypeOf } from '@main/core/telemetry/agent-type';+import type {+ TelemetryAgentRemoveFailure,+ TelemetryAgentRemoveTrigger,+ TelemetryLocationKind,+} from '@main/core/telemetry/events';+import { agentRemoveTriggerOf } from '@main/core/telemetry/narrow';+import { trackEvent } from '@main/core/telemetry/telemetry-service';import { viewStateService } from '@main/core/view-state/view-state-service';import { db } from '@main/db/client';import { agents, sessions } from '@main/db/schema';@@ -32,8 +44,37 @@ export type DeleteAgentOptions = {* left registered on the server.*/deleteInSwitch: boolean;+ /**+ * Whether a person removed this agent or a server teardown swept it up.+ *+ * Required, because the same function serves both: wiping a managed server+ * deletes every agent on it one at a time, and a default here would file that+ * as a room full of people deleting their agents at once.+ */+ trigger: TelemetryAgentRemoveTrigger;};+/**+ * The agent has no Switch identity to delete.+ *+ * A class rather than a message, so the reason can be reported as a code+ * without matching on prose that a later edit would quietly change.+ */+class AgentNotLinkedToSwitchError extends Error {}++/** What went wrong, as a code taken from the error's own type. */+function removeFailureReason(error: unknown): TelemetryAgentRemoveFailure {+ if (error instanceof AgentNotLinkedToSwitchError) return 'not_linked_to_switch';+ if (error instanceof GatewayError) return `gateway_${error.kind}`;+ return 'error';+}++/** Where the agent runs, from a row already read. `unknown` when it has gone. */+function locationKindOfRow(location: Location | null): TelemetryLocationKind {+ if (!location) return 'unknown';+ return location.sshHost ? 'remote' : 'local';+}+/*** Delete this agent's own identity on the Switch server — and ONLY this one.*@@ -48,12 +89,14 @@ export type DeleteAgentOptions = {*/async function deleteAgentInSwitch(agent: Agent): Promise<void> {if (!agent.serverId || !agent.switchAgentId) {- throw new Error(+ throw new AgentNotLinkedToSwitchError(`Agent ${agent.id} is not linked to a Switch server, so it cannot be deleted in Switch.`);}const server = await getServer(agent.serverId);- if (!server) throw new Error(`No Switch server with id ${agent.serverId}`);+ if (!server) {+ throw new AgentNotLinkedToSwitchError(`No Switch server with id ${agent.serverId}`);+ }await gatewayDeleteAgent(server, agent.switchAgentId);}@@ -155,7 +198,34 @@ async function killRemoteSidecar(agent: Agent): Promise<void> {export async function deleteAgent(agentId: string, options: DeleteAgentOptions): Promise<void> {const agent = await getAgentById(agentId);const location = agent ? await getAgentLocation(agent).catch(() => null) : null;+ // Captured before the row goes: after the delete below there is nothing left+ // to describe what was removed.+ const shape = {+ agent_type: agent ? agentTypeOf(agent.providerId) : ('unknown' as const),+ location: locationKindOfRow(location),+ delete_in_switch: options.deleteInSwitch,+ trigger: agentRemoveTriggerOf(options.trigger),+ };++ try {+ await removeAgent(agentId, agent, location, options);+ } catch (error) {+ trackEvent('agent_removed', {+ ...shape,+ outcome: 'failure',+ failure_reason: removeFailureReason(error),+ });+ throw error;+ }+ trackEvent('agent_removed', { ...shape, outcome: 'success', failure_reason: 'none' });+}+async function removeAgent(+ agentId: string,+ agent: Agent | undefined,+ location: Location | null,+ options: DeleteAgentOptions+): Promise<void> {// Gateway cascade first: fail loud before touching local state so a failure// never leaves the row deleted but the Switch identity orphaned.if (options.deleteInSwitch && agent) {@@ -194,5 +264,10 @@ export async function deleteAgent(agentId: string, options: DeleteAgentOptions):}await db.delete(agents).where(eq(agents.id, agentId));+ // The session rows go with it, by a foreign key rather than by any code here,+ // so nothing else announces their end. Without this every session an agent+ // owned reports a start and no finish — the row is gone and no later pass can+ // notice it left.+ for (const row of sessionRows) sessionHooks._emit('session:deleted', row.id);agentEvents._emit('agent:deleted', agentId);}diff --git a/console/apps/switch-console-desktop/src/main/core/agents/onboard-agent.test.ts b/console/apps/switch-console-desktop/src/main/core/agents/onboard-agent.test.tsnew file mode 100644index 000000000..fde36e2f4--- /dev/null+++ b/console/apps/switch-console-desktop/src/main/core/agents/onboard-agent.test.ts@@ -0,0 +1,182 @@+import { beforeEach, describe, expect, it, vi } from 'vitest';++/**+ * What onboarding an already-configured directory reports.+ *+ * One control reaches this path — a folder dropped on the sidebar — and it+ * fails in four typed ways, none of which used to be counted at all.+ */++const { h } = vi.hoisted(() => ({+ h: {+ trackEvent: vi.fn(),+ emit: vi.fn(),+ validDirectory: true,+ detected: { agentId: 'sw-1', apiEndpoint: 'https://switch.example.com' } as {+ agentId: string;+ apiEndpoint: string;+ } | null,+ agentExists: true,+ unauthorized: false,+ server: { id: 'srv-1', name: 'Switch', apiUrl: 'https://switch.example.com' } as {+ id: string;+ name: string;+ apiUrl: string;+ managementKind?: string;+ sshHost?: string;+ } | null,+ },+}));++vi.mock('@main/core/telemetry/telemetry-service', () => ({ trackEvent: h.trackEvent }));+vi.mock('@main/core/locations/path-utils', () => ({+ checkIsValidDirectory: () => h.validDirectory,+}));+vi.mock('@main/core/locations/store', () => ({+ ensureLocation: vi.fn(async () => ({ id: 'loc' })),+}));+vi.mock('@main/core/locations/location-manager', () => ({+ locationManager: { openLocation: vi.fn(async () => {}) },+}));+vi.mock('@main/core/switch-rooms/switch-credentials', () => ({+ readSwitchAgentCredentials: vi.fn(async () => null),+}));+vi.mock('@main/core/switch-servers/servers-store', () => ({+ getServer: vi.fn(async () => h.server),+}));+vi.mock('@main/core/switch-servers/gateway-client', () => {+ class GatewayError extends Error {+ constructor(readonly kind: string) {+ super(kind);+ }+ }+ return {+ GatewayError,+ agentExistsOnServer: vi.fn(async () => {+ if (h.unauthorized) throw new GatewayError('unauthorized');+ return h.agentExists;+ }),+ };+});+vi.mock('@main/lib/logger', () => ({+ log: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },+}));+vi.mock('./detect', () => ({ detectSwitchAgent: vi.fn(async () => h.detected) }));+vi.mock('./detect-remote', () => ({ detectSwitchAgentRemote: vi.fn(async () => h.detected) }));+vi.mock('./createAgent', () => ({+ createAgent: vi.fn(async (input: Record<string, unknown>) => ({ ...input })),+}));+vi.mock('./agent-events', () => ({ agentEvents: { _emit: h.emit } }));+vi.mock('./setAgentAutoSession', () => ({+ reconcileAgentAutoSessionFromGateway: vi.fn(async () => {}),+}));+vi.mock('./write-switch-settings', () => ({ writeAgentNeutralSettings: vi.fn(async () => {}) }));++const { onboardAgent } = await import('./onboard-agent');++function params(overrides: Record<string, unknown> = {}) {+ return {+ name: 'repo',+ serverId: 'srv-1',+ providerId: 'claude' as const,+ dir: '/repo',+ ...overrides,+ };+}++beforeEach(() => {+ vi.clearAllMocks();+ h.validDirectory = true;+ h.detected = { agentId: 'sw-1', apiEndpoint: 'https://switch.example.com' };+ h.agentExists = true;+ h.unauthorized = false;+ h.server = { id: 'srv-1', name: 'Switch', apiUrl: 'https://switch.example.com' };+});++describe('where an onboarded agent is said to have come from', () => {+ it('names the sidebar, the one control that reaches this path', async () => {+ // The first-run checklist opens the add-agent modal instead, which reports+ // `onboarding` from there. Naming this one the same pooled the two and left+ // dragging a folder onto the sidebar with no count of its own.+ const result = await onboardAgent(params());++ expect(result.success).toBe(true);+ expect(h.emit).toHaveBeenCalledWith('agent:created', expect.anything(), 'sidebar');+ });++ it('names it on a failure too', async () => {+ h.validDirectory = false;++ await onboardAgent(params());++ expect(h.trackEvent).toHaveBeenCalledWith(+ 'agent_created',+ expect.objectContaining({ entry_point: 'sidebar' })+ );+ });+});++describe('what a failed onboarding reports', () => {+ it('reports nothing itself when the agent is created', async () => {+ // The success comes from the `agent:created` hook; reporting here as well+ // would double-count it.+ await onboardAgent(params());++ expect(h.trackEvent).not.toHaveBeenCalled();+ });++ it('reports a directory that is not a Switch agent', async () => {+ h.detected = null;++ await onboardAgent(params());++ expect(h.trackEvent).toHaveBeenCalledWith('agent_created', {+ agent_type: 'claude',+ location: 'local',+ outcome: 'failure',+ failure_reason: 'not_configured',+ entry_point: 'sidebar',+ });+ });++ it('reports a server this app is not signed in to as unauthenticated', async () => {+ h.unauthorized = true;++ await onboardAgent(params());++ expect(h.trackEvent).toHaveBeenCalledWith(+ 'agent_created',+ expect.objectContaining({ failure_reason: 'unauthenticated' })+ );+ });++ it('reports an identity the chosen server does not have', async () => {+ h.agentExists = false;++ await onboardAgent(params());++ expect(h.trackEvent).toHaveBeenCalledWith(+ 'agent_created',+ expect.objectContaining({ outcome: 'failure', failure_reason: 'agent_not_on_server' })+ );+ });++ it('describes a remote onboarding as remote', async () => {+ h.detected = null;++ await onboardAgent(params({ sshHost: 'build-box' }));++ expect(h.trackEvent).toHaveBeenCalledWith(+ 'agent_created',+ expect.objectContaining({ location: 'remote' })+ );+ });++ it('never puts the directory in the payload', async () => {+ h.validDirectory = false;++ await onboardAgent(params({ dir: '/Users/someone/secret-project' }));++ expect(JSON.stringify(h.trackEvent.mock.calls)).not.toContain('secret-project');+ });+});diff --git a/console/apps/switch-console-desktop/src/main/core/agents/onboard-agent.ts b/console/apps/switch-console-desktop/src/main/core/agents/onboard-agent.tsindex d1999ff4b..33224fb09 100644--- a/console/apps/switch-console-desktop/src/main/core/agents/onboard-agent.ts+++ b/console/apps/switch-console-desktop/src/main/core/agents/onboard-agent.ts@@ -6,6 +6,9 @@ import { ensureLocation } from '@main/core/locations/store';import { readSwitchAgentCredentials } from '@main/core/switch-rooms/switch-credentials';import { agentExistsOnServer, GatewayError } from '@main/core/switch-servers/gateway-client';import { getServer } from '@main/core/switch-servers/servers-store';+import { agentTypeOf } from '@main/core/telemetry/agent-type';+import type { TelemetryAgentCreateFailure } from '@main/core/telemetry/events';+import { trackEvent } from '@main/core/telemetry/telemetry-service';import { log } from '@main/lib/logger';import type {OnboardAgentError,@@ -13,6 +16,7 @@ import type {OnboardAgentResult,} from '@shared/core/agents/onboarding';import type { SwitchServer } from '@shared/core/switch-servers/switch-servers';+import type { UiEntryPoint } from '@shared/core/telemetry/reporting';import { basenameFromAnyPath } from '@shared/path-name';import { agentEvents } from './agent-events';import { createAgent } from './createAgent';@@ -21,6 +25,55 @@ import { detectSwitchAgentRemote } from './detect-remote';import { reconcileAgentAutoSessionFromGateway } from './setAgentAutoSession';import { writeAgentNeutralSettings } from './write-switch-settings';+/**+ * Where an agent onboarded through here came from.+ *+ * One control reaches this path: a folder dropped on the sidebar, which the+ * location manager turns into an onboard. The first-run checklist opens the+ * add-agent modal instead and reports `onboarding` from there, so naming this+ * one `onboarding` too would pool the two and leave drag-and-drop with no count+ * of its own.+ */+const ONBOARD_ENTRY_POINT: UiEntryPoint = 'sidebar';++/**+ * The error's discriminant as a reportable code. Never its message — every one+ * of these carries a directory path.+ *+ * Only the unauthenticated case has a name of its own in the reportable set. A+ * directory that is not a Switch agent and an identity the chosen server does+ * not have are both real, distinct walls, and both land in `error` because+ * naming them is a change to the reported vocabulary rather than to this map.+ */+const ONBOARD_AGENT_FAILURE_REASON: Record<OnboardAgentError['type'], TelemetryAgentCreateFailure> =+ {+ 'invalid-directory': 'not_configured',+ 'switch-agent-not-on-server': 'agent_not_on_server',+ 'switch-server-unauthenticated': 'unauthenticated',+ error: 'error',+ };++/**+ * Report an onboarding that did not happen, and hand the error back unchanged.+ *+ * The success is reported from the `agent:created` hook, which by definition+ * only fires when one happened. The location comes from the parameters rather+ * than a row, because there is no row.+ */+function reportFailedOnboard(+ params: OnboardAgentParams,+ error: OnboardAgentError+): OnboardAgentResult {+ trackEvent('agent_created', {+ agent_type: agentTypeOf(params.providerId),+ location: params.sshHost ? 'remote' : 'local',+ outcome: 'failure',+ failure_reason: ONBOARD_AGENT_FAILURE_REASON[error.type],+ entry_point: ONBOARD_ENTRY_POINT,+ });+ return err(error);+}+/*** Gate agent creation on the chosen server actually owning the detected agent* (and on being signed in). Every agent in the app is bound to a usable server@@ -94,7 +147,11 @@ export async function onboardAgent(params: OnboardAgentParams): Promise<OnboardAlet switchAgent;if (sshHost === null) {if (!checkIsValidDirectory(params.dir)) {- return err({ type: 'invalid-directory', dir: params.dir, message: 'Invalid directory' });+ return reportFailedOnboard(params, {+ type: 'invalid-directory',+ dir: params.dir,+ message: 'Invalid directory',+ });}// Onboarding a directory == onboarding a Switch agent. Reject directories// that are not configured as one (no `.claude/settings.local.json` block).@@ -103,7 +160,7 @@ export async function onboardAgent(params: OnboardAgentParams): Promise<OnboardAswitchAgent = await detectSwitchAgentRemote(sshHost, params.dir);}if (!switchAgent) {- return err({+ return reportFailedOnboard(params, {type: 'invalid-directory',dir: params.dir,message:@@ -114,13 +171,17 @@ export async function onboardAgent(params: OnboardAgentParams): Promise<OnboardA}const serverError = await verifyAgentOnServer(params.serverId, switchAgent.agentId, params.dir);- if (serverError) return err(serverError);+ if (serverError) return reportFailedOnboard(params, serverError);const server = await getServer(params.serverId);if (server) {const locationError = managedServerLocationError(server, sshHost);if (locationError) {- return err({ type: 'invalid-directory', dir: params.dir, message: locationError });+ return reportFailedOnboard(params, {+ type: 'invalid-directory',+ dir: params.dir,+ message: locationError,+ });}}@@ -177,6 +238,6 @@ export async function onboardAgent(params: OnboardAgentParams): Promise<OnboardA});await locationManager.openLocation(location);- agentEvents._emit('agent:created', agent);+ agentEvents._emit('agent:created', agent, ONBOARD_ENTRY_POINT);return ok(agent);}diff --git a/console/apps/switch-console-desktop/src/main/core/agents/onboard-location-agents.ts b/console/apps/switch-console-desktop/src/main/core/agents/onboard-location-agents.tsindex 37ce11818..5aef43a4b 100644--- a/console/apps/switch-console-desktop/src/main/core/agents/onboard-location-agents.ts+++ b/console/apps/switch-console-desktop/src/main/core/agents/onboard-location-agents.ts@@ -271,6 +271,8 @@ export async function onboardLocationAgents(}await locationManager.openLocation(location);- for (const agent of created) agentEvents._emit('agent:created', agent);+ // Nothing on the way here names a control, and a directory's worth of+ // definitions can arrive in one call, so `unknown` is what these are.+ for (const agent of created) agentEvents._emit('agent:created', agent, 'unknown');return ok(created);}diff --git a/console/apps/switch-console-desktop/src/main/core/agents/remote-session-reconciler.ts b/console/apps/switch-console-desktop/src/main/core/agents/remote-session-reconciler.tsindex 29a0ce2c1..b4a725f46 100644--- a/console/apps/switch-console-desktop/src/main/core/agents/remote-session-reconciler.ts+++ b/console/apps/switch-console-desktop/src/main/core/agents/remote-session-reconciler.ts@@ -6,6 +6,7 @@ import { httpGetJsonOverChannel } from '@main/core/agent-runtime/impl/sidecar-htimport { sshConnectionIdForHost } from '@main/core/locations/location-transport';import type { HostReachabilityChange } from '@main/core/remote-hosts/host-reachability-service';import { hostReachabilityService } from '@main/core/remote-hosts/production-host-reachability';+import { formatProvisionSessionError } from '@main/core/sessions/provision-session-error';import { sessionHooks } from '@main/core/sessions/session-hooks';import { sessionService } from '@main/core/sessions/session-service';import { sshConnectionManager } from '@main/core/ssh/lifecycle/production-ssh-connection-manager';@@ -508,6 +509,10 @@ class RemoteSessionReconciler {// opens the session — a first sync against a busy host would otherwise// spawn one PTY per adopted session in a single pass.attach: false,+ // Nobody started this here: the agent was already running on the VM and+ // this row is catching up with it, so it is reported apart from the+ // sessions this app actually started.+ startSource: 'adopted',});if (!result.success) {if (result.error.type === 'already-exists') {@@ -531,13 +536,16 @@ class RemoteSessionReconciler {// not session:provisioned — without the latter an open renderer leaves the// session stuck "Setting up session…". provisionSession is idempotent and// emits the provisioned event the renderer needs.- await sessionService.provisionSession(sessionId).catch((error) => {+ // The failure is a value now, not a rejection: a `.catch` here would never+ // run and the failure would pass in silence.+ const provisioned = await sessionService.provisionSession(sessionId);+ if (!provisioned.success) {log.warn('RemoteSessionReconciler: post-adopt provision-reconcile failed', {agentId: agent.id,sessionId,- error: String(error),+ error: formatProvisionSessionError(provisioned.error),});- });+ }let adoptedIds = this.adopted.get(agent.id);if (!adoptedIds) {adoptedIds = new Set();diff --git a/console/apps/switch-console-desktop/src/main/core/agents/reset-remote-agent.lifecycle.test.ts b/console/apps/switch-console-desktop/src/main/core/agents/reset-remote-agent.lifecycle.test.tsnew file mode 100644index 000000000..5fdd43327--- /dev/null+++ b/console/apps/switch-console-desktop/src/main/core/agents/reset-remote-agent.lifecycle.test.ts@@ -0,0 +1,201 @@+import { beforeEach, describe, expect, it, vi } from 'vitest';++/**+ * What a reset tells the rest of the app about the sessions it removes.+ *+ * A reset deletes rows for sessions that are still, as far as anything watching+ * is concerned, running. It used to announce that only to the renderer, so+ * anything in the main process tracking a session's lifetime never heard the+ * end — including the emitter, which had reported every one of them starting.+ */++const { h } = vi.hoisted(() => ({+ h: {+ sessionRows: [{ id: 's-1' }] as { id: string }[],+ deletedChanges: 1,+ hookEmit: vi.fn(),+ ipcEmit: vi.fn(),+ teardownSession: vi.fn(async () => {}),+ trackEvent: vi.fn(),+ remoteLocation: { id: 'loc' } as { id: string } | null,+ connect: null as null | (() => never),+ killFails: false,+ },+}));++vi.mock('drizzle-orm', () => ({ eq: () => ({}) }));+vi.mock('@main/db/schema', () => ({ sessions: { id: 'id', agentId: 'agentId' } }));+vi.mock('@main/db/client', () => ({+ db: {+ select: () => ({ from: () => ({ where: () => Promise.resolve(h.sessionRows) }) }),+ delete: () => ({ where: () => Promise.resolve({ changes: h.deletedChanges }) }),+ },+}));++vi.mock('@main/core/sessions/session-hooks', () => ({+ sessionHooks: { _emit: h.hookEmit },+}));+vi.mock('@main/lib/events', () => ({ events: { emit: h.ipcEmit } }));+vi.mock('@main/core/telemetry/telemetry-service', () => ({ trackEvent: h.trackEvent }));+vi.mock('@main/core/sessions/session-runtime-manager', () => ({+ sessionRuntimeManager: { teardownSession: h.teardownSession },+}));+vi.mock('@main/core/switch-rooms/switch-room-service', () => ({+ switchRoomService: { clearSession: vi.fn() },+}));+vi.mock('@main/core/view-state/view-state-service', () => ({+ viewStateService: { del: vi.fn(async () => {}) },+}));+vi.mock('@main/lib/logger', () => ({+ log: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },+}));++vi.mock('./getAgentById', () => ({+ getAgentById: vi.fn(async () => ({+ id: 'agent-1',+ name: 'codex-hoot',+ providerId: 'codex',+ autoApprove: false,+ })),+}));+vi.mock('./agent-location', () => ({+ getRemoteAgentLocation: vi.fn(async () => h.remoteLocation),+}));+vi.mock('./agent-launch-config', () => ({ agentLaunchSpecialization: vi.fn(async () => null) }));+vi.mock('./connect-remote-agent', () => ({+ connectRemoteAgent: vi.fn(async () => {+ if (h.connect) h.connect();+ return {+ host: {+ exec: vi.fn(async () => {+ if (h.killFails) throw new Error('tmux: kill-session failed');+ }),+ },+ remoteRepoDir: '/srv/repo',+ ctx: {},+ connectionId: 'c-1',+ proxy: { forwardOut: vi.fn() },+ };+ }),+}));+vi.mock('./remote-session-reconciler', () => ({ remoteSessionReconciler: { stop: vi.fn() } }));+vi.mock('./remote-watcher', () => ({+ ensureRemoteWatcher: vi.fn(async () => {}),+ startRemoteDiscovery: vi.fn(async () => {}),+}));+vi.mock('@main/core/agent-runtime/impl/remote-sidecar-launcher', () => ({+ writeWatchEnabled: vi.fn(async () => {}),+ agentSidecarTmuxName: (repoDir: string, slug: string) => `switch-sidecar-${slug}`,+}));+// No sidecar to reach, so the reset works from the database rows alone.+vi.mock('@main/core/agent-runtime/impl/ensure-agent-sidecar', () => ({+ probeAgentSidecar: vi.fn(async () => null),+}));+vi.mock('@main/core/agent-runtime/impl/sidecar-http', () => ({ httpGetJsonOverChannel: vi.fn() }));+vi.mock('@main/app/deeplinks', () => ({ DEEPLINK_SCHEME: 'switch' }));++const { resetRemoteAgent } = await import('./reset-remote-agent');++beforeEach(() => {+ vi.clearAllMocks();+ h.sessionRows = [{ id: 's-1' }];+ h.deletedChanges = 1;+ h.remoteLocation = { id: 'loc' };+ h.connect = null;+ h.killFails = false;+});++describe('resetting a remote agent', () => {+ it('announces each removed session on the lifecycle bus, not only to the renderer', async () => {+ await resetRemoteAgent('agent-1');++ expect(h.hookEmit).toHaveBeenCalledWith('session:deleted', 's-1');+ expect(h.ipcEmit).toHaveBeenCalled();+ });++ it('announces every session it removes', async () => {+ h.sessionRows = [{ id: 's-1' }, { id: 's-2' }, { id: 's-3' }];++ await resetRemoteAgent('agent-1');++ expect(+ h.hookEmit.mock.calls.map(([, id]) => id as string).toSorted((a, b) => a.localeCompare(b))+ ).toEqual(['s-1', 's-2', 's-3']);+ });++ it('says nothing for a row that was already gone', async () => {+ // A delete that changed nothing is not a session ending; announcing it+ // would end the same session twice across the two delete paths.+ h.deletedChanges = 0;++ await resetRemoteAgent('agent-1');++ expect(h.hookEmit).not.toHaveBeenCalled();+ expect(h.ipcEmit).not.toHaveBeenCalled();+ });+});++describe('what a reset reports', () => {+ it('reports a reset that completed', async () => {+ await resetRemoteAgent('agent-1');++ expect(h.trackEvent).toHaveBeenCalledWith('agent_reset', {+ agent_type: 'codex',+ outcome: 'success',+ failure_reason: 'none',+ });+ });++ it('reports a local agent as the reason it cannot be reset', async () => {+ h.remoteLocation = null;++ await expect(resetRemoteAgent('agent-1')).rejects.toThrow();++ expect(h.trackEvent).toHaveBeenCalledWith(+ 'agent_reset',+ expect.objectContaining({ outcome: 'failure', failure_reason: 'not_remote' })+ );+ });++ it('reports an unreachable host as a connect failure, never its message', async () => {+ // The commonest reason a remote reset fails, and the one thing here that is+ // nothing to do with the app. Its own text is not ours to enumerate, and+ // never ours to send.+ h.connect = () => {+ throw new Error('ssh: connect to host /Users/someone/secret-project failed');+ };++ await expect(resetRemoteAgent('agent-1')).rejects.toThrow();++ expect(h.trackEvent).toHaveBeenCalledWith(+ 'agent_reset',+ expect.objectContaining({ outcome: 'failure', failure_reason: 'connect' })+ );+ expect(JSON.stringify(h.trackEvent.mock.calls)).not.toContain('secret-project');+ });++ it('hands the transport its own error back untouched', async () => {+ // The interface branches on the error's class to explain an unreachable+ // host. Naming the failure must not cost it that.+ class HostUnreachableError extends Error {}+ const thrown = new HostUnreachableError('Host build-box is unreachable');+ h.connect = () => {+ throw thrown;+ };++ await expect(resetRemoteAgent('agent-1')).rejects.toBe(thrown);+ });++ it('reports a teardown failure as a plain error, not as a connect failure', async () => {+ // Getting to the host worked; killing its panes did not. Only the first is+ // the host's doing.+ h.killFails = true;++ await expect(resetRemoteAgent('agent-1')).rejects.toThrow();++ expect(h.trackEvent).toHaveBeenCalledWith(+ 'agent_reset',+ expect.objectContaining({ outcome: 'failure', failure_reason: 'error' })+ );+ });+});diff --git a/console/apps/switch-console-desktop/src/main/core/agents/reset-remote-agent.ts b/console/apps/switch-console-desktop/src/main/core/agents/reset-remote-agent.tsindex 98b927717..66725bdb0 100644--- a/console/apps/switch-console-desktop/src/main/core/agents/reset-remote-agent.ts+++ b/console/apps/switch-console-desktop/src/main/core/agents/reset-remote-agent.ts@@ -7,8 +7,12 @@ import {writeWatchEnabled,} from '@main/core/agent-runtime/impl/remote-sidecar-launcher';import { httpGetJsonOverChannel } from '@main/core/agent-runtime/impl/sidecar-http';+import { sessionHooks } from '@main/core/sessions/session-hooks';import { sessionRuntimeManager } from '@main/core/sessions/session-runtime-manager';import { switchRoomService } from '@main/core/switch-rooms/switch-room-service';+import { agentTypeOf } from '@main/core/telemetry/agent-type';+import type { TelemetryAgentResetFailure } from '@main/core/telemetry/events';+import { trackEvent } from '@main/core/telemetry/telemetry-service';import { viewStateService } from '@main/core/view-state/view-state-service';import { db } from '@main/db/client';import { sessions } from '@main/db/schema';@@ -26,6 +30,46 @@ import { buildKillTmuxScript, resetTmuxTargets } from './reset-remote-agent-tmuxconst SESSIONS_REQUEST_TIMEOUT_MS = 10_000;+/**+ * A reset that failed for a reason worth naming.+ *+ * The reason travels as a field rather than in the message, so it can be+ * reported as a code without anyone matching on prose. Everything left unnamed —+ * an exec, the transport dropping mid-reset — is reported as `error`, because a+ * remote failure's own text is not ours to enumerate and never ours to send.+ */+class AgentResetError extends Error {+ constructor(+ readonly reason: TelemetryAgentResetFailure,+ message: string+ ) {+ super(message);+ }+}++/**+ * Reasons for failures this module did not raise itself.+ *+ * The one worth naming most comes from below: reaching the host fails with the+ * transport's own error, and the interface branches on that error's class to+ * tell someone their host is unreachable rather than that "something went+ * wrong". Wrapping it in one of ours would buy a code and lose that, so the+ * reason is remembered beside the error and the error travels untouched.+ */+const namedFailures = new WeakMap<object, TelemetryAgentResetFailure>();++/** Remember why an error happened, and hand it straight back. */+function named<E>(error: E, reason: TelemetryAgentResetFailure): E {+ if (typeof error === 'object' && error !== null) namedFailures.set(error, reason);+ return error;+}++function resetFailureReason(error: unknown): TelemetryAgentResetFailure {+ if (error instanceof AgentResetError) return error.reason;+ if (typeof error === 'object' && error !== null) return namedFailures.get(error) ?? 'error';+ return 'error';+}+interface SidecarSessionsResponse {sessions: Array<{ sessionId: string; roomId: string | null }>;}@@ -113,6 +157,11 @@ async function removeLocalSession(sessionId: string): Promise<void> {const deleted = await db.delete(sessions).where(eq(sessions.id, sessionId));await viewStateService.del(`session:${sessionId}`);if (deleted.changes === 0) return;+ // The same pair the reconciler's remote-driven delete fires: the hook for+ // anything in the main process that tracks a session's lifetime, and the IPC+ // event so an open window drops the row. Firing only the second leaves a+ // session that was reported as started and never as ended.+ sessionHooks._emit('session:deleted', sessionId);events.emit(sessionDeletedChannel, { sessionId });}@@ -132,17 +181,51 @@ async function removeLocalSession(sessionId: string): Promise<void> {*/export async function resetRemoteAgent(agentId: string): Promise<void> {const agent = await getAgentById(agentId);- if (!agent) throw new Error(`No agent with id ${agentId}`);+ if (!agent) {+ trackEvent('agent_reset', {+ agent_type: 'unknown',+ outcome: 'failure',+ failure_reason: 'agent_not_found',+ });+ throw new AgentResetError('agent_not_found', `No agent with id ${agentId}`);+ }++ const agentType = agentTypeOf(agent.providerId);+ try {+ await runReset(agentId, agent);+ } catch (error) {+ trackEvent('agent_reset', {+ agent_type: agentType,+ outcome: 'failure',+ failure_reason: resetFailureReason(error),+ });+ throw error;+ }+ trackEvent('agent_reset', { agent_type: agentType, outcome: 'success', failure_reason: 'none' });+}++async function runReset(agentId: string, agent: Agent): Promise<void> {const location = await getRemoteAgentLocation(agent);if (!location) {- throw new Error(`Agent ${agentId} is not remote, so it cannot be reset.`);+ throw new AgentResetError(+ 'not_remote',+ `Agent ${agentId} is not remote, so it cannot be reset.`+ );}// Stop this client's discovery loop before killing anything so a reconcile tick// cannot re-adopt a session from a stale snapshot mid-reset.remoteSessionReconciler.stop(agentId);- const conn = await connectRemoteAgent(agent);+ let conn: RemoteConn;+ try {+ conn = await connectRemoteAgent(agent);+ } catch (error) {+ // The likeliest way a reset fails, and the only step here that depends on+ // something outside the app — worth separating from everything the app+ // itself can get wrong.+ throw named(error, 'connect');+ }const credsSlug = agent.name ?? agent.id;// Silence the VM watcher first so it cannot auto-start a fresh session betweendiff --git a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/local-server-service.ts b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/local-server-service.tsindex c82a8f66a..3a7d39f15 100644--- a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/local-server-service.ts+++ b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/local-server-service.ts@@ -1,5 +1,10 @@import { deleteAgentsForServer } from '@main/core/switch-servers/delete-server-agents';import { getManagedServer } from '@main/core/switch-servers/servers-store';+import {+ reportManagedServerOutcome,+ reportManagedServerStart,+ reportManagedServerStartThrew,+} from '@main/core/telemetry/managed-server';import { events } from '@main/lib/events';import { log } from '@main/lib/logger';import { COMPATIBLE_SWITCH_VERSION } from '@shared/app-identity';@@ -180,11 +185,13 @@ class LocalServerService {drift: null,});}+ reportManagedServerStart('local', result);return result;} catch (error) {const message = error instanceof Error ? error.message : String(error);log.error('local-switch-server: start failed', { error });this.setStatus({ phase: 'error', error: message });+ reportManagedServerStartThrew('local');return { kind: 'error', message };} finally {host.dispose();@@ -201,11 +208,13 @@ class LocalServerService {this.setStatus({ phase: 'stopping', message: 'Stopping containers…' });await stopStack(host);this.setStatus({ phase: 'stopped', message: null, error: null });+ reportManagedServerOutcome('stop', 'local', 'success');} catch (error) {this.setStatus({phase: 'error',error: error instanceof Error ? error.message : String(error),});+ reportManagedServerOutcome('stop', 'local', 'failure');throw error;} finally {host.dispose();@@ -231,11 +240,13 @@ class LocalServerService {this.setStatus({ phase: 'stopping', message: 'Destroying containers and data…' });await resetStack(host);this.setStatus({ phase: 'stopped', message: null, error: null });+ reportManagedServerOutcome('reset', 'local', 'success');} catch (error) {this.setStatus({phase: 'error',error: error instanceof Error ? error.message : String(error),});+ reportManagedServerOutcome('reset', 'local', 'failure');throw error;} finally {host.dispose();diff --git a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/remote-server-service.ts b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/remote-server-service.tsindex 49a40631d..967176ebf 100644--- a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/remote-server-service.ts+++ b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/remote-server-service.ts@@ -5,6 +5,11 @@ import {getRemoteManagedServer,listManagedServers,} from '@main/core/switch-servers/servers-store';+import {+ reportManagedServerOutcome,+ reportManagedServerStart,+ reportManagedServerStartThrew,+} from '@main/core/telemetry/managed-server';import { events } from '@main/lib/events';import { log } from '@main/lib/logger';import { COMPATIBLE_SWITCH_VERSION } from '@shared/app-identity';@@ -202,12 +207,14 @@ class RemoteServerService {drift: null,});}+ reportManagedServerStart('remote', result);return result;} catch (error) {host?.dispose();const message = error instanceof Error ? error.message : String(error);log.error(`remote-switch-server: start failed for ${sshHost}`, { error });this.setStatus(sshHost, { phase: 'error', error: message });+ reportManagedServerStartThrew('remote');return { kind: 'error', message };} finally {this.busy.delete(sshHost);@@ -218,22 +225,28 @@ class RemoteServerService {async stop(sshHost: string): Promise<void> {if (this.busy.has(sshHost))throw new Error(`An operation is already in progress for ${sshHost}.`);- hostReachabilityService.requireReachable(sshHost);this.busy.add(sshHost);- const host = this.hosts.get(sshHost) ?? (await createRemoteServerHost(sshHost));+ // Reaching the host is part of stopping it, and the part that most often+ // fails: a stack is torn down because its host is misbehaving. Both steps+ // therefore sit inside the region that reports, and inside the one that+ // gives the busy flag back.+ let host: RemoteServerHost | null = null;try {+ hostReachabilityService.requireReachable(sshHost);+ host = this.hosts.get(sshHost) ?? (await createRemoteServerHost(sshHost));this.setStatus(sshHost, { phase: 'stopping', message: 'Stopping containers…' });await stopStack(host);this.setStatus(sshHost, { phase: 'stopped', message: null, error: null });+ reportManagedServerOutcome('stop', 'remote', 'success');} catch (error) {this.setStatus(sshHost, {phase: 'error',error: error instanceof Error ? error.message : String(error),});+ reportManagedServerOutcome('stop', 'remote', 'failure');throw error;} finally {- host.dispose();- this.hosts.delete(sshHost);+ this.releaseHost(sshHost, host);this.busy.delete(sshHost);}}@@ -246,29 +259,47 @@ class RemoteServerService {async reset(sshHost: string): Promise<void> {if (this.busy.has(sshHost))throw new Error(`An operation is already in progress for ${sshHost}.`);- hostReachabilityService.requireReachable(sshHost);this.busy.add(sshHost);- const host = this.hosts.get(sshHost) ?? (await createRemoteServerHost(sshHost));+ // Reaching the host is inside the reported region for the reason `stop`+ // gives.+ let host: RemoteServerHost | null = null;try {+ hostReachabilityService.requireReachable(sshHost);+ host = this.hosts.get(sshHost) ?? (await createRemoteServerHost(sshHost));this.setStatus(sshHost, { phase: 'stopping', message: 'Removing agents…' });const server = await getRemoteManagedServer(sshHost);if (server) await deleteAgentsForServer(server.id);this.setStatus(sshHost, { phase: 'stopping', message: 'Destroying containers and data…' });await resetStack(host);this.setStatus(sshHost, { phase: 'stopped', message: null, error: null });+ reportManagedServerOutcome('reset', 'remote', 'success');} catch (error) {this.setStatus(sshHost, {phase: 'error',error: error instanceof Error ? error.message : String(error),});+ reportManagedServerOutcome('reset', 'remote', 'failure');throw error;} finally {- host.dispose();- this.hosts.delete(sshHost);+ this.releaseHost(sshHost, host);this.busy.delete(sshHost);}}+ /**+ * Drop the host a teardown used, and the map entry it may have come from.+ *+ * Null when the teardown never got one — the alias is then left alone rather+ * than un-keyed, because an entry dropped without being disposed strands the+ * port-forward it owns and lets the reachability reconciler adopt the same+ * stack a second time.+ */+ private releaseHost(sshHost: string, host: RemoteServerHost | null): void {+ if (!host) return;+ host.dispose();+ this.hosts.delete(sshHost);+ }+/** Abort in-flight health waits and drop all forwards (app quit). The remote* containers keep running; only the desktop-side tunnels close. */dispose(): void {diff --git a/console/apps/switch-console-desktop/src/main/core/providers/controller.ts b/console/apps/switch-console-desktop/src/main/core/providers/controller.tsindex 91b68bb52..ffc9a18b8 100644--- a/console/apps/switch-console-desktop/src/main/core/providers/controller.ts+++ b/console/apps/switch-console-desktop/src/main/core/providers/controller.ts@@ -5,6 +5,11 @@ import type {HostDependencySelection,InstallOverride,} from '@switch-console/core/deps/runtime';+import { agentTypeOf } from '@main/core/telemetry/agent-type';+import { cliFailureReason } from '@main/core/telemetry/cli-failure';+import type { TelemetryCliAction } from '@main/core/telemetry/events';+import { installMethodOf } from '@main/core/telemetry/narrow';+import { trackEvent } from '@main/core/telemetry/telemetry-service';import type { ProviderCustomConfig } from '@shared/core/app-settings';import type { AgentProviderId } from '@shared/core/providers/agent-provider-registry';import { createRPCController } from '@shared/lib/ipc/rpc';@@ -26,6 +31,30 @@ const enrichHostDep = (hostDep: Parameters<typeof agentUpdateService.enrichHostDependency>[1]) => agentUpdateService.enrichHostDependency(id, hostDep);+/**+ * Report installing, updating or removing an agent's CLI.+ *+ * `target` is always local here. This controller accepts a connection id and+ * discards it — `getDependencyManager` returns the local manager whatever it is+ * given — so nothing reached through it runs anywhere else. The genuinely remote+ * equivalents live on the remote-hosts controller and report themselves.+ */+function reportCliAction(+ action: TelemetryCliAction,+ id: string,+ method: InstallMethod | undefined,+ result: { success: boolean; error?: { type?: string } }+): void {+ trackEvent('agent_cli_action', {+ agent_type: agentTypeOf(id),+ target: 'local',+ install_method: installMethodOf(method),+ action,+ outcome: result.success ? 'success' : 'failure',+ failure_reason: cliFailureReason(result),+ });+}+export const providersController = createRPCController({// ── Metadata ────────────────────────────────────────────────────────────────@@ -70,6 +99,7 @@ export const providersController = createRPCController({install: async (id: AgentProviderId, connectionId?: string, method?: InstallMethod) => {const mgr = await getDependencyManager(connectionId);const result = await mgr.install(id, method);+ reportCliAction('install', id, method, result);if (result.success) {// Persist the chosen method as an override, or clear to auto when no method was chosen.// Do NOT auto-promote the inferred method — that would freeze a heuristic guess.@@ -82,12 +112,16 @@ export const providersController = createRPCController({update: async (id: AgentProviderId, connectionId?: string, method?: InstallMethod) => {const mgr = await getDependencyManager(connectionId);- return mgr.update(id, method);+ const result = await mgr.update(id, method);+ reportCliAction('update', id, method, result);+ return result;},uninstall: async (id: AgentProviderId, connectionId?: string, method?: InstallMethod) => {const mgr = await getDependencyManager(connectionId);- return mgr.uninstall(id, method);+ const result = await mgr.uninstall(id, method);+ reportCliAction('uninstall', id, method, result);+ return result;},// ── Settings ─────────────────────────────────────────────────────────────────diff --git a/console/apps/switch-console-desktop/src/main/core/remote-hosts/controller.ts b/console/apps/switch-console-desktop/src/main/core/remote-hosts/controller.tsindex e540492bc..b7c8769ac 100644--- a/console/apps/switch-console-desktop/src/main/core/remote-hosts/controller.ts+++ b/console/apps/switch-console-desktop/src/main/core/remote-hosts/controller.ts@@ -13,6 +13,11 @@ import {remoteDependencyDescriptor,} from '@main/core/dependencies/remote-dependency-manager';import { getRemoteSwitchSetupService } from '@main/core/switch-setup/remote-switch-setup';+import { agentTypeOf } from '@main/core/telemetry/agent-type';+import { cliFailureReason } from '@main/core/telemetry/cli-failure';+import type { TelemetryCliAction } from '@main/core/telemetry/events';+import { installMethodOf } from '@main/core/telemetry/narrow';+import { trackEvent } from '@main/core/telemetry/telemetry-service';import { hostBlockedReason, type HostReachability } from '@shared/core/remote-hosts/reachability';import type { HostSetupPlan } from '@shared/core/remote-hosts/setup';import { createRPCController } from '@shared/lib/ipc/rpc';@@ -82,6 +87,33 @@ async function probeDeps(sshHost: string): Promise<RemoteDependencyView[]> {return views;}+/**+ * Report a CLI action that really did run on a remote host.+ *+ * The local controller's equivalent always reports `local`; this one always+ * reports `remote`, which is the only difference between them. The host is never+ * named — `remote` is the whole of what is said about where.+ *+ * The id here is a dependency id, which may be a core dependency rather than an+ * agent, so it goes through the same narrowing as anywhere else and reports+ * `unknown` when it is not a provider we know.+ */+function reportRemoteCliAction(+ action: TelemetryCliAction,+ id: string,+ method: InstallMethod | undefined,+ result: { success: boolean; error?: { type?: string } }+): void {+ trackEvent('agent_cli_action', {+ agent_type: agentTypeOf(id),+ target: 'remote',+ install_method: installMethodOf(method),+ action,+ outcome: result.success ? 'success' : 'failure',+ failure_reason: cliFailureReason(result),+ });+}+export const remoteHostsController = createRPCController({/** SSH aliases from ~/.ssh/config, for the onboarding picker. */listSshConfigHosts: (): Promise<string[]> => listSshConfigHosts(),@@ -109,12 +141,30 @@ export const remoteHostsController = createRPCController({hostReachabilityService.checkNow(sshHost),/** Verify reachability, then onboard (or rename) the host. */- onboardHost: async (params: { sshHost: string; name: string }): Promise<RemoteHost> => {+ onboardHost: async (params: {+ sshHost: string;+ name: string;+ /**+ * Whether the alias came from the machine's SSH config or was typed in. Only+ * the form knows — both write through here — and it is the difference+ * between a host the app offered and one someone had to know the name of.+ */+ pickedFromSshConfig: boolean;+ }): Promise<RemoteHost> => {const test = await testConnection(params.sshHost);if (!test.ok) {+ trackEvent('host_onboarded', {+ outcome: 'failure',+ picked_from_ssh_config: params.pickedFromSshConfig === true,+ });throw new Error(`Cannot reach ${params.sshHost}: ${test.message}`);}- return upsertRemoteHost({ sshHost: params.sshHost, name: params.name });+ const host = await upsertRemoteHost({ sshHost: params.sshHost, name: params.name });+ trackEvent('host_onboarded', {+ outcome: 'success',+ picked_from_ssh_config: params.pickedFromSshConfig === true,+ });+ return host;},/**@@ -124,10 +174,16 @@ export const remoteHostsController = createRPCController({* against stale state.*/removeHost: async (sshHost: string): Promise<void> => {- await removeRemoteHost(sshHost);- await discardSetupPlan(sshHost);- await deletePersistedReachability(sshHost);- evictRemoteDependencyManager(sshHost);+ try {+ await removeRemoteHost(sshHost);+ await discardSetupPlan(sshHost);+ await deletePersistedReachability(sshHost);+ evictRemoteDependencyManager(sshHost);+ } catch (error) {+ trackEvent('host_removed', { outcome: 'failure' });+ throw error;+ }+ trackEvent('host_removed', { outcome: 'success' });},/** The host's persisted setup plan, or null if setup has never been run. */@@ -181,12 +237,16 @@ export const remoteHostsController = createRPCController({method?: InstallMethod;}): Promise<DependencyInstallResult> => {const manager = await getRemoteDependencyManager(params.sshHost);- return manager.install(params.id, params.method);+ const result = await manager.install(params.id, params.method);+ reportRemoteCliAction('install', params.id, params.method, result);+ return result;},updateDep: async (params: { sshHost: string; id: string }): Promise<DependencyUpdateResult> => {const manager = await getRemoteDependencyManager(params.sshHost);- return manager.update(params.id);+ const result = await manager.update(params.id);+ reportRemoteCliAction('update', params.id, undefined, result);+ return result;},uninstallDep: async (params: {@@ -194,7 +254,9 @@ export const remoteHostsController = createRPCController({id: string;}): Promise<DependencyUninstallResult> => {const manager = await getRemoteDependencyManager(params.sshHost);- return manager.uninstall(params.id);+ const result = await manager.uninstall(params.id);+ reportRemoteCliAction('uninstall', params.id, undefined, result);+ return result;},/** Switch connector plugin status for every Switch-supported agent type on the host. */diff --git a/console/apps/switch-console-desktop/src/main/core/remote-hosts/setup/host-setup-service.test.ts b/console/apps/switch-console-desktop/src/main/core/remote-hosts/setup/host-setup-service.test.tsindex 245397500..967a250b5 100644--- a/console/apps/switch-console-desktop/src/main/core/remote-hosts/setup/host-setup-service.test.ts+++ b/console/apps/switch-console-desktop/src/main/core/remote-hosts/setup/host-setup-service.test.ts@@ -10,8 +10,25 @@ const mocks = vi.hoisted(() => ({remoteDependencyDescriptor: vi.fn(),probeGhAuthStatus: vi.fn(),getUpdateInfo: vi.fn(),+ runSingleStep: vi.fn(),+ runnerUpdateStep: vi.fn(),+ runnerSkip: vi.fn(),}));+// The runner sequences steps and knows nothing about reporting; what it does+// with a step is its own test's business. Only the plan it hands back matters+// here.+vi.mock('./host-setup-runner', () => ({+ HostSetupRunner: class {+ runSingleStep = mocks.runSingleStep;+ updateStep = mocks.runnerUpdateStep;+ skip = mocks.runnerSkip;+ checkAll = vi.fn();+ checkStep = vi.fn();+ },+}));++vi.mock('@main/core/telemetry/telemetry-service', () => ({ trackEvent: vi.fn() }));vi.mock('@main/core/switch-setup/remote-switch-setup', () => ({getRemoteSwitchSetupService: () =>Promise.resolve({@@ -63,9 +80,17 @@ vi.mock('@main/core/dependencies/install-output', () => ({}));import type { HostDependencyManager } from '@switch-console/core/deps/runtime';+import { getRemoteDependencyManager } from '@main/core/dependencies/remote-dependency-manager';+import { trackEvent } from '@main/core/telemetry/telemetry-service';import type { HostSetupPlan, HostSetupStep } from '@shared/core/remote-hosts/setup';-import { checkStep, readAllSetupPlans } from './host-setup-service';-import { listSetupPlans, saveSetupPlan } from './setup-plan-store';+import {+ checkStep,+ installSetupStep,+ readAllSetupPlans,+ skipSetupStep,+ updateSetupStep,+} from './host-setup-service';+import { getSetupPlan, listSetupPlans, saveSetupPlan } from './setup-plan-store';const SSH_HOST = 'dev-vm';@@ -410,3 +435,150 @@ describe('offering a CLI update only when it can be carried out', () => {});});});++/**+ * What a step reports, and about which row.+ *+ * The dimensions are the whole value of this event: a page of rows, each for a+ * different agent type, and the question it answers is which of them people get+ * stuck on. A failure filed under the wrong row is worse than an unreported one,+ * because it moves a count somewhere it does not belong.+ */+describe('what a setup step reports', () => {+ const HOST = 'report-vm';++ /** A plan with the ids the real builder produces, for the paths that read one. */+ function plan(): HostSetupPlan {+ return {+ sshHost: HOST,+ status: 'idle',+ steps: [+ step({ id: 'node', kind: 'core-dependency', name: 'Node.js', dependsOn: [] }),+ step({ id: 'claude', kind: 'agent-cli', name: 'Claude Code', dependsOn: ['node'] }),+ step({ id: 'claude:plugin' }),+ ],+ currentStepId: null,+ createdAt: '2026-01-01T00:00:00.000Z',+ updatedAt: '2026-01-01T00:00:00.000Z',+ };+ }++ function satisfying(planIn: HostSetupPlan, stepId: string): HostSetupPlan {+ return {+ ...planIn,+ steps: planIn.steps.map((s) => (s.id === stepId ? { ...s, state: 'satisfied' } : s)),+ };+ }++ beforeEach(() => {+ vi.mocked(getRemoteDependencyManager).mockResolvedValue(manager);+ vi.mocked(getSetupPlan).mockResolvedValue(plan());+ mocks.runSingleStep.mockImplementation(async (p: HostSetupPlan, id: string) =>+ satisfying(p, id)+ );+ mocks.runnerUpdateStep.mockImplementation(async (p: HostSetupPlan, id: string) =>+ satisfying(p, id)+ );+ mocks.runnerSkip.mockImplementation(async (p: HostSetupPlan) => p);+ });++ it('names the row an install succeeded on', async () => {+ await installSetupStep(HOST, 'claude');++ expect(trackEvent).toHaveBeenCalledWith('host_setup_step', {+ step_kind: 'agent-cli',+ agent_type: 'claude',+ action: 'install',+ outcome: 'success',+ });+ });++ it('names the row an install failed on, when the host could not be reached', async () => {+ // Resolving the dependency manager is where the SSH connection is opened, so+ // an unreachable host fails here — before the runner is ever asked to do+ // anything. It is still that row, of that kind, for that agent type.+ vi.mocked(getRemoteDependencyManager).mockRejectedValueOnce(new Error('ssh: connect failed'));++ await expect(installSetupStep(HOST, 'claude')).rejects.toThrow();++ expect(trackEvent).toHaveBeenCalledWith('host_setup_step', {+ step_kind: 'agent-cli',+ agent_type: 'claude',+ action: 'install',+ outcome: 'failure',+ });+ });++ it('names the agent type behind a connector row', async () => {+ vi.mocked(getRemoteDependencyManager).mockRejectedValueOnce(new Error('ssh: connect failed'));++ await expect(installSetupStep(HOST, 'claude:plugin')).rejects.toThrow();++ expect(trackEvent).toHaveBeenCalledWith(+ 'host_setup_step',+ expect.objectContaining({ step_kind: 'agent-plugin', agent_type: 'claude' })+ );+ });++ it('claims no agent type for a host-level dependency', async () => {+ vi.mocked(getRemoteDependencyManager).mockRejectedValueOnce(new Error('ssh: connect failed'));++ await expect(installSetupStep(HOST, 'node')).rejects.toThrow();++ expect(trackEvent).toHaveBeenCalledWith(+ 'host_setup_step',+ expect.objectContaining({ step_kind: 'core-dependency', agent_type: 'unknown' })+ );+ });++ it('names the row an update failed on', async () => {+ mocks.runnerUpdateStep.mockRejectedValueOnce(new Error('npm: EACCES'));++ await expect(updateSetupStep(HOST, 'claude')).rejects.toThrow();++ expect(trackEvent).toHaveBeenCalledWith('host_setup_step', {+ step_kind: 'agent-cli',+ agent_type: 'claude',+ action: 'update',+ outcome: 'failure',+ });+ });++ it('reports a skip that took', async () => {+ await skipSetupStep(HOST, 'claude');++ expect(trackEvent).toHaveBeenCalledWith('host_setup_step', {+ step_kind: 'agent-cli',+ agent_type: 'claude',+ action: 'skip',+ outcome: 'success',+ });+ });++ it('reports a skip that never took', async () => {+ // Install and update both report a throw; a skip that threw used to report+ // nothing, so the same wall counted differently depending on which button+ // ran into it.+ vi.mocked(getRemoteDependencyManager).mockRejectedValueOnce(new Error('ssh: connect failed'));++ await expect(skipSetupStep(HOST, 'claude')).rejects.toThrow();++ expect(trackEvent).toHaveBeenCalledWith('host_setup_step', {+ step_kind: 'agent-cli',+ agent_type: 'claude',+ action: 'skip',+ outcome: 'failure',+ });+ });++ it('still reports when there is no plan to name the row from', async () => {+ vi.mocked(saveSetupPlan).mockRejectedValueOnce(new Error('disk is full'));++ await expect(installSetupStep(HOST, 'claude')).rejects.toThrow();++ expect(trackEvent).toHaveBeenCalledWith(+ 'host_setup_step',+ expect.objectContaining({ action: 'install', outcome: 'failure' })+ );+ });+});diff --git a/console/apps/switch-console-desktop/src/main/core/remote-hosts/setup/host-setup-service.ts b/console/apps/switch-console-desktop/src/main/core/remote-hosts/setup/host-setup-service.tsindex 4d31033b2..101889897 100644--- a/console/apps/switch-console-desktop/src/main/core/remote-hosts/setup/host-setup-service.ts+++ b/console/apps/switch-console-desktop/src/main/core/remote-hosts/setup/host-setup-service.ts@@ -17,9 +17,13 @@ import {} from '@main/core/dependencies/remote-dependency-manager';import { listPlugins } from '@main/core/providers/plugin-registry';import { getRemoteSwitchSetupService } from '@main/core/switch-setup/remote-switch-setup';+import { agentTypeOf } from '@main/core/telemetry/agent-type';+import type { TelemetryHostSetupAction, TelemetryOutcome } from '@main/core/telemetry/events';+import { trackEvent } from '@main/core/telemetry/telemetry-service';import { events } from '@main/lib/events';import { log } from '@main/lib/logger';import {+ agentIdForStep,hostSetupActivityEventChannel,hostSetupPlanEventChannel,type HostSetupPlan,@@ -399,12 +403,56 @@ export async function recheckSetupStep(sshHost: string, stepId: string): Promise}}+/** Whether the step ended in the state the action was trying to reach. */+function stepOutcome(plan: HostSetupPlan, stepId: string): TelemetryOutcome {+ const step = plan.steps.find((s) => s.id === stepId);+ return step?.state === 'satisfied' ? 'success' : 'failure';+}++/**+ * Report what a setup step did.+ *+ * The outcome is read back off the step in the returned plan rather than from+ * the call returning at all: these runners resolve with a plan whether or not+ * the step succeeded, so "it did not throw" is not the same as "it worked".+ * A step that is not in the returned plan, which should not happen, is reported+ * as a failure rather than silently as a success.+ *+ * The plan is what names the step, so it is also where the two dimensions come+ * from — a row that failed because the host was unreachable is still that row,+ * of that kind, for that agent type. It is nullable because a run can fail+ * before there is a plan at all, and both dimensions are then reported as+ * `unknown` rather than folded into a real kind's tally.+ */+function reportSetupStep(+ plan: HostSetupPlan | null,+ stepId: string,+ action: TelemetryHostSetupAction,+ outcome: TelemetryOutcome+): void {+ const step = plan?.steps.find((s) => s.id === stepId);+ trackEvent('host_setup_step', {+ step_kind: step?.kind ?? 'unknown',+ // Null for a host-level dependency, which belongs to no agent.+ agent_type: agentTypeOf(step ? (agentIdForStep(step) ?? '') : ''),+ action,+ outcome,+ });+}+export async function installSetupStep(sshHost: string, stepId: string): Promise<HostSetupPlan> {- const plan = await ensureSetupPlan(sshHost);- const manager = await getRemoteDependencyManager(sshHost);+ // Both of these reach past the app — resolving the dependency manager opens+ // the SSH connection — so they belong inside the guarded region: a host that+ // cannot be reached is the commonest way an install never happens.+ let plan: HostSetupPlan | null = null;try {- return await runnerFor(sshHost, manager).runSingleStep(plan, stepId);+ plan = await ensureSetupPlan(sshHost);+ const manager = await getRemoteDependencyManager(sshHost);+ const next = await runnerFor(sshHost, manager).runSingleStep(plan, stepId);+ reportSetupStep(next, stepId, 'install', stepOutcome(next, stepId));+ return next;} catch (error) {+ reportSetupStep(plan, stepId, 'install', 'failure');log.warn('[HostSetup] step install stopped', {event: 'host-setup-step-install-stopped',sshHost,@@ -417,11 +465,15 @@ export async function installSetupStep(sshHost: string, stepId: string): Promise/** Update one step to the newest available version — the per-row Update button. */export async function updateSetupStep(sshHost: string, stepId: string): Promise<HostSetupPlan> {- const plan = await ensureSetupPlan(sshHost);- const manager = await getRemoteDependencyManager(sshHost);+ let plan: HostSetupPlan | null = null;try {- return await runnerFor(sshHost, manager).updateStep(plan, stepId);+ plan = await ensureSetupPlan(sshHost);+ const manager = await getRemoteDependencyManager(sshHost);+ const next = await runnerFor(sshHost, manager).updateStep(plan, stepId);+ reportSetupStep(next, stepId, 'update', stepOutcome(next, stepId));+ return next;} catch (error) {+ reportSetupStep(plan, stepId, 'update', 'failure');log.warn('[HostSetup] step update stopped', {event: 'host-setup-step-update-stopped',sshHost,@@ -436,8 +488,20 @@ export async function updateSetupStep(sshHost: string, stepId: string): Promise<export async function skipSetupStep(sshHost: string, stepId: string): Promise<HostSetupPlan> {const plan = await getSetupPlan(sshHost);if (!plan) throw new Error(`No setup plan exists for ${sshHost}`);- const manager = await getRemoteDependencyManager(sshHost);- return await runnerFor(sshHost, manager).skip(plan, stepId);+ try {+ const manager = await getRemoteDependencyManager(sshHost);+ const next = await runnerFor(sshHost, manager).skip(plan, stepId);+ // A skip always succeeds at what it is for — moving past the step. Whether the+ // dependency is satisfied is a different question, and the point of counting+ // skips is that someone decided to go on without it.+ reportSetupStep(next, stepId, 'skip', 'success');+ return next;+ } catch (error) {+ // Reaching the host can fail here too, and a skip that never took is not the+ // decision this event exists to count.+ reportSetupStep(plan, stepId, 'skip', 'failure');+ throw error;+ }}/** Drop a host's plan and its runner — called when the host is removed. */diff --git a/console/apps/switch-console-desktop/src/main/core/search/controller.telemetry.test.ts b/console/apps/switch-console-desktop/src/main/core/search/controller.telemetry.test.tsnew file mode 100644index 000000000..d011c3089--- /dev/null+++ b/console/apps/switch-console-desktop/src/main/core/search/controller.telemetry.test.ts@@ -0,0 +1,87 @@+import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';++/**+ * What a search reports, and how often.+ *+ * The palette searches as you type, so the interesting property of this event is+ * that there is one of it per search rather than one per keystroke.+ */++const { h } = vi.hoisted(() => ({ h: { trackEvent: vi.fn(), search: vi.fn() } }));++vi.mock('@main/core/telemetry/telemetry-service', () => ({ trackEvent: h.trackEvent }));+vi.mock('./search-service', () => ({ searchService: { search: h.search } }));++const { searchController } = await import('./controller');++function answers(status: string, count: number) {+ h.search.mockReturnValue({ status, items: Array.from({ length: count }, (_, i) => ({ id: i })) });+}++beforeEach(() => {+ vi.useFakeTimers();+ vi.clearAllMocks();+ answers('ok', 3);+});++afterEach(() => vi.useRealTimers());++describe('reporting a search', () => {+ it('reports once for a burst of typing, not once per keystroke', () => {+ for (const query of ['s', 'se', 'ses', 'sess']) {+ searchController.commandPalette({ query } as never);+ }+ vi.advanceTimersByTime(2_000);++ expect(h.trackEvent).toHaveBeenCalledTimes(1);+ });++ it('reports what the last search of the burst found, not the first', () => {+ answers('ok', 9);+ searchController.commandPalette({ query: 's' } as never);+ answers('ok', 1);+ searchController.commandPalette({ query: 'sessi' } as never);+ vi.advanceTimersByTime(2_000);++ expect(h.trackEvent).toHaveBeenCalledWith('search_performed', {+ status: 'ok',+ result_count: 1,+ });+ });++ it('reports two searches separated by a pause as two', () => {+ searchController.commandPalette({ query: 'agent' } as never);+ vi.advanceTimersByTime(2_000);+ searchController.commandPalette({ query: 'room' } as never);+ vi.advanceTimersByTime(2_000);++ expect(h.trackEvent).toHaveBeenCalledTimes(2);+ });++ it('says nothing when the palette merely opens', () => {+ // An empty query asks for recents, which is not a search anyone ran.+ answers('recents', 5);+ searchController.commandPalette({ query: '' } as never);+ vi.advanceTimersByTime(2_000);++ expect(h.trackEvent).not.toHaveBeenCalled();+ });++ it('reports a search that failed, which is not the same as finding nothing', () => {+ answers('failed', 0);+ searchController.commandPalette({ query: 'agent' } as never);+ vi.advanceTimersByTime(2_000);++ expect(h.trackEvent).toHaveBeenCalledWith('search_performed', {+ status: 'failed',+ result_count: 0,+ });+ });++ it('never carries the query', () => {+ searchController.commandPalette({ query: 'secret-project-name' } as never);+ vi.advanceTimersByTime(2_000);++ expect(JSON.stringify(h.trackEvent.mock.calls)).not.toContain('secret-project-name');+ });+});diff --git a/console/apps/switch-console-desktop/src/main/core/search/controller.ts b/console/apps/switch-console-desktop/src/main/core/search/controller.tsindex ab7204ee3..e8247eedc 100644--- a/console/apps/switch-console-desktop/src/main/core/search/controller.ts+++ b/console/apps/switch-console-desktop/src/main/core/search/controller.ts@@ -1,7 +1,57 @@-import type { CommandPaletteQuery } from '@shared/core/search';+import { trackEvent } from '@main/core/telemetry/telemetry-service';+import type { CommandPaletteQuery, SearchStatus } from '@shared/core/search';import { createRPCController } from '@shared/lib/ipc/rpc';import { searchService } from './search-service';+/**+ * How long after the last keystroke a search counts as finished.+ *+ * The palette searches as you type, on a 100ms debounce — shorter than most+ * people type — so a six-character query runs four or five searches. Reporting+ * each would make this the most frequent event in the catalogue by a wide margin+ * and say nothing the last one does not, which is the high-volume reporting the+ * catalogue is meant to stay clear of.+ */+const SEARCH_SETTLE_MS = 1_000;++let pendingSearch: { status: SearchStatus; count: number } | null = null;+let searchTimer: NodeJS.Timeout | null = null;++/**+ * Report one search per burst of typing: the last one, which is the query the+ * person actually meant and the result they actually saw.+ *+ * The timer is unref'd so a pending report cannot hold the process open at quit,+ * and a burst still in flight when the app closes is simply not reported —+ * losing the tail of a session's searches is a far smaller error than counting+ * every keystroke as a search.+ */+function reportSearch(status: SearchStatus, count: number): void {+ pendingSearch = { status, count };+ if (searchTimer) clearTimeout(searchTimer);+ searchTimer = setTimeout(() => {+ const settled = pendingSearch;+ pendingSearch = null;+ searchTimer = null;+ if (settled) {+ trackEvent('search_performed', { status: settled.status, result_count: settled.count });+ }+ }, SEARCH_SETTLE_MS);+ searchTimer.unref?.();+}+export const searchController = createRPCController({- commandPalette: (query: CommandPaletteQuery) => searchService.search(query),+ // The query itself is never reported: what someone types is theirs, and the+ // answerable questions — does search find anything, and how often does it fail+ // outright — are answered by the outcome and the count alone.+ commandPalette: (query: CommandPaletteQuery) => {+ const result = searchService.search(query);+ // Only a search someone actually ran. Opening the palette asks for recents+ // with an empty query, and reporting that would count a search nobody+ // performed — once per open, which would quickly outnumber the real ones.+ if (result.status !== 'recents') {+ reportSearch(result.status, result.items.length);+ }+ return result;+ },});diff --git a/console/apps/switch-console-desktop/src/main/core/search/search-service.db.test.ts b/console/apps/switch-console-desktop/src/main/core/search/search-service.db.test.tsindex 49d8af4f3..b8bdaa76d 100644--- a/console/apps/switch-console-desktop/src/main/core/search/search-service.db.test.ts+++ b/console/apps/switch-console-desktop/src/main/core/search/search-service.db.test.ts@@ -136,7 +136,8 @@ describe('searchService', () => {agentEvents._emit('agent:created',- agentRecord({ id: 'agent-3', name: 'newcomer-bot', locationId: 'loc-1' })+ agentRecord({ id: 'agent-3', name: 'newcomer-bot', locationId: 'loc-1' }),+ 'unknown');expect(titles(searchService.search({ query: 'newcomer' }).items)).toEqual(['newcomer-bot']);@@ -270,7 +271,11 @@ describe('searchService', () => {['a-noise', 'co-test'],['a-noise2', 'test-agent-tt'],]) {- agentEvents._emit('agent:created', agentRecord({ id, name, locationId: 'loc-1' }));+ agentEvents._emit(+ 'agent:created',+ agentRecord({ id, name, locationId: 'loc-1' }),+ 'unknown'+ );}expect(titles(searchService.search({ query: 'test-tt' }).items)).toEqual(['test-tt']);@@ -282,7 +287,8 @@ describe('searchService', () => {searchService.initialize();agentEvents._emit('agent:created',- agentRecord({ id: 'a-cc', name: 'reviewer cc', locationId: 'loc-1' })+ agentRecord({ id: 'a-cc', name: 'reviewer cc', locationId: 'loc-1' }),+ 'unknown');expect(titles(searchService.search({ query: 'reviewer cc' }).items)).toEqual(['reviewer cc']);@@ -301,7 +307,8 @@ describe('searchService', () => {searchService.initialize();agentEvents._emit('agent:created',- agentRecord({ id: 'agent-4', name: 'codex-runner', locationId: 'loc-1' })+ agentRecord({ id: 'agent-4', name: 'codex-runner', locationId: 'loc-1' }),+ 'unknown');// 'codex' is agent-2's provider (a keyword) and agent-4's name.diff --git a/console/apps/switch-console-desktop/src/main/core/sessions/controller.ts b/console/apps/switch-console-desktop/src/main/core/sessions/controller.tsindex fba10a5f4..f3eb8ee8e 100644--- a/console/apps/switch-console-desktop/src/main/core/sessions/controller.ts+++ b/console/apps/switch-console-desktop/src/main/core/sessions/controller.ts@@ -1,5 +1,10 @@import { remoteAttachmentPool } from '@main/core/agent-runtime/attachment/production-remote-attachment-pool';+import type { AttachState } from '@main/core/agent-runtime/attachment/types';+import { agentTypeOf } from '@main/core/telemetry/agent-type';+import { provisionTriggerOf } from '@main/core/telemetry/narrow';+import { trackEvent } from '@main/core/telemetry/telemetry-service';import type { CreateSessionParams, SessionLifecycleStatus } from '@shared/core/sessions/sessions';+import type { SessionProvisionTrigger } from '@shared/core/telemetry/reporting';import { createRPCController } from '@shared/lib/ipc/rpc';import { generateSessionName } from './name-generation/generateSessionName';import { dehydrateSession } from './operations/dehydrateSession';@@ -9,6 +14,29 @@ import { markSessionSeen } from './operations/markSessionSeen';import { restartSessionAgent } from './operations/restartSessionAgent';import { sessionService } from './session-service';+/**+ * Report an attach the user asked for and waited on.+ *+ * Only the two states that are an answer. `attaching` is not over yet, and+ * `detached` covers both a local session, which never attaches, and an attach+ * cancelled because the transport dropped — one failure for the whole host, not+ * one per session queued behind it.+ */+function reportAttach(sessionId: string, state: AttachState): void {+ if (state !== 'attached' && state !== 'failed') return;++ // Not awaited: describing the attach needs a read the person attaching should+ // not be waiting on, and a failure to describe it must not fail the attach.+ void getSession(sessionId)+ .then((session) => {+ trackEvent('session_attached', {+ agent_type: session ? agentTypeOf(session.providerId) : 'unknown',+ outcome: state === 'attached' ? 'success' : 'failure',+ });+ })+ .catch(() => {});+}+export const sessionController = createRPCController({getSession,hydrateSession,@@ -26,7 +54,9 @@ export const sessionController = createRPCController({},/** Attach a session's terminal on request — the detached state's Attach button. */async attachSession(sessionId: string) {- return remoteAttachmentPool.requestAttach(sessionId, 'user');+ const state = await remoteAttachmentPool.requestAttach(sessionId, 'user');+ reportAttach(sessionId, state);+ return state;},/** Close a session's terminal, leaving its agent running on the VM. */async detachSession(sessionId: string) {@@ -72,8 +102,11 @@ export const sessionController = createRPCController({async restartAgent(sessionId: string) {return restartSessionAgent(sessionId);},- async provisionSession(sessionId: string) {- return sessionService.provisionSession(sessionId);+ async provisionSession(params: { sessionId: string; trigger: SessionProvisionTrigger }) {+ // The trigger is typed on this side of the channel but arrives from the+ // renderer, so it is checked rather than trusted — an unrecognised one+ // falls back to `initial`, which reports nothing.+ return sessionService.provisionSession(params.sessionId, provisionTriggerOf(params.trigger));},generateSessionName,});diff --git a/console/apps/switch-console-desktop/src/main/core/sessions/provision-session-error.ts b/console/apps/switch-console-desktop/src/main/core/sessions/provision-session-error.tsindex cacc12fc7..b75a8476f 100644--- a/console/apps/switch-console-desktop/src/main/core/sessions/provision-session-error.ts+++ b/console/apps/switch-console-desktop/src/main/core/sessions/provision-session-error.ts@@ -6,6 +6,12 @@ export const TEARDOWN_SCRIPT_WAIT_MS = 10_000;export type ProvisionSessionError =| { type: 'timeout'; message: string; timeout: number; step: ProvisionStep | null }+ /**+ * The session's agent is not open, so there is nowhere to provision it. The+ * one failure here a user can act on, and the reason it is separated from+ * `error`: it is undone by reopening the agent, not by retrying.+ */+ | { type: 'location-not-open'; message: string }| { type: 'error'; message: string };export type TeardownSessionError =@@ -30,7 +36,7 @@ export function toTeardownError(e: unknown): TeardownSessionError {export function isProvisionSessionError(e: unknown): e is ProvisionSessionError {if (!e || typeof e !== 'object' || !('type' in e)) return false;const type = (e as { type?: string }).type;- return type === 'timeout' || type === 'error';+ return type === 'timeout' || type === 'location-not-open' || type === 'error';}export function formatTeardownSessionError(error: TeardownSessionError): string {@@ -46,6 +52,7 @@ export function formatProvisionSessionError(error: ProvisionSessionError): strinswitch (error.type) {case 'timeout':return error.step ? `${error.message} (step: ${error.step})` : error.message;+ case 'location-not-open':case 'error':return error.message;}diff --git a/console/apps/switch-console-desktop/src/main/core/sessions/session-service.telemetry.test.ts b/console/apps/switch-console-desktop/src/main/core/sessions/session-service.telemetry.test.tsnew file mode 100644index 000000000..bd3c16580--- /dev/null+++ b/console/apps/switch-console-desktop/src/main/core/sessions/session-service.telemetry.test.ts@@ -0,0 +1,311 @@+import { describe, expect, it, vi, beforeEach } from 'vitest';++/**+ * What a session start reports when it does not happen.+ *+ * The success is reported from the `session:created` hook, which only fires on+ * one — so a start that fails has no bus to be heard on and is reported at the+ * service instead. These cover that the two describe the same thing in the same+ * terms, since the whole point is to compare them.+ */++const { hoisted } = vi.hoisted(() => ({+ hoisted: {+ createSession: vi.fn(),+ getAgentById: vi.fn(),+ getLocationById: vi.fn(),+ trackEvent: vi.fn(),+ getSession: vi.fn(),+ sessionRows: vi.fn(),+ mapSessionRow: vi.fn(),+ getLocation: vi.fn(),+ },+}));++vi.mock('./operations/createSession', () => ({ createSession: hoisted.createSession }));+vi.mock('@main/core/agents/getAgentById', () => ({ getAgentById: hoisted.getAgentById }));+vi.mock('@main/core/locations/store', () => ({ getLocationById: hoisted.getLocationById }));+vi.mock('@main/core/telemetry/telemetry-service', () => ({ trackEvent: hoisted.trackEvent }));++// Provisioning reads the session row through the query builder before it can+// get as far as anything else, so the chain has to be walkable — otherwise the+// failure under test is the double, not the code.+vi.mock('@main/db/client', () => ({+ db: {+ select: () => ({ from: () => ({ where: () => ({ limit: () => hoisted.sessionRows() }) }) }),+ },+}));+vi.mock('@main/db/schema', () => ({ sessions: {} }));+vi.mock('@main/lib/events', () => ({ events: { emit: vi.fn() } }));+vi.mock('@main/lib/logger', () => ({+ log: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },+}));+vi.mock('@main/core/locations/location-manager', () => ({+ locationManager: { getLocation: hoisted.getLocation },+}));+vi.mock('./session-builder', () => ({ provisionSessionRuntime: vi.fn() }));+vi.mock('./session-runtime-manager', () => ({+ sessionRuntimeManager: { registerSession: vi.fn(), getAgent: vi.fn() },+}));+vi.mock('./utils/utils', () => ({ mapSessionRowToSession: hoisted.mapSessionRow }));+vi.mock('./operations/archiveSession', () => ({ archiveSession: vi.fn() }));+vi.mock('./operations/deleteSession', () => ({ deleteSession: vi.fn() }));+vi.mock('./operations/ensureSessionAttachable', () => ({ ensureSessionAttachable: vi.fn() }));+vi.mock('./operations/getSessions', () => ({ getSessions: vi.fn() }));+vi.mock('./operations/getSession', () => ({ getSession: hoisted.getSession }));+vi.mock('./operations/renameSession', () => ({ renameSession: vi.fn() }));+vi.mock('./operations/restoreSession', () => ({ restoreSession: vi.fn() }));+vi.mock('./operations/setSessionPinned', () => ({ setSessionPinned: vi.fn() }));+vi.mock('./operations/updateSessionStatus', () => ({ updateSessionStatus: vi.fn() }));++const { sessionService } = await import('./session-service');++const PARAMS = {+ id: 's-1',+ agentId: 'agent-1',+ title: 'Session',+ entryPoint: 'sidebar',+} as const;++/**+ * Let the deferred report run.+ *+ * Reporting is deliberately not awaited by the operation — it does database+ * reads the caller must not wait on — so a test has to give it a turn.+ */+const settle = () => new Promise((resolve) => setTimeout(resolve, 0));++function failWith(type: string, extra: Record<string, unknown> = {}) {+ hoisted.createSession.mockResolvedValue({ success: false, error: { type, ...extra } });+}++beforeEach(() => {+ vi.clearAllMocks();+ hoisted.getAgentById.mockResolvedValue({ id: 'agent-1', providerId: 'codex', locationId: 'loc' });+ hoisted.getLocationById.mockResolvedValue({ id: 'loc', sshHost: null });+});++describe('a session start that fails', () => {+ it('reports the failure with the reason as a code', async () => {+ failWith('spawn-failed', { message: 'boom' });++ await sessionService.createSession({ ...PARAMS });++ await settle();++ expect(hoisted.trackEvent).toHaveBeenCalledWith(+ 'session_started',+ expect.objectContaining({+ outcome: 'failure',+ failure_reason: 'spawn_failed',+ agent_type: 'codex',+ location: 'local',+ entry_point: 'sidebar',+ })+ );+ });++ it('never puts the spawn error message in the payload', async () => {+ failWith('spawn-failed', { message: 'ENOENT /Users/someone/secret-project/bin/codex' });++ await sessionService.createSession({ ...PARAMS });++ await settle();++ expect(JSON.stringify(hoisted.trackEvent.mock.calls)).not.toContain('secret-project');+ });++ it('says unknown rather than guessing when the agent is what is missing', async () => {+ // `agent-not-found` is itself one of the failures, so there is nothing to+ // read the shape from — and a guess here would be indistinguishable from a+ // real answer.+ hoisted.getAgentById.mockResolvedValue(undefined);+ failWith('agent-not-found');++ await sessionService.createSession({ ...PARAMS });++ await settle();++ expect(hoisted.trackEvent).toHaveBeenCalledWith(+ 'session_started',+ expect.objectContaining({+ agent_type: 'unknown',+ location: 'unknown',+ failure_reason: 'agent_not_found',+ })+ );+ });++ it('records whether a room and a prompt were asked for, not what they were', async () => {+ failWith('already-exists');++ await sessionService.createSession({+ ...PARAMS,+ initialPrompt: 'connect to room alpha and audit the deploy',+ connectedToRoom: true,+ });++ await settle();++ const [, properties] = hoisted.trackEvent.mock.calls[0] as [string, Record<string, unknown>];+ expect(properties.has_initial_prompt).toBe(true);+ expect(properties.connected_to_room).toBe(true);+ expect(JSON.stringify(properties)).not.toContain('alpha');+ });++ it('says no room was asked for when the caller declared none', async () => {+ failWith('already-exists');++ await sessionService.createSession({ ...PARAMS });++ await settle();++ expect(hoisted.trackEvent).toHaveBeenCalledWith(+ 'session_started',+ expect.objectContaining({ connected_to_room: false })+ );+ });++ it('treats whitespace as no prompt, the same test the create path applies', async () => {+ failWith('already-exists');++ await sessionService.createSession({ ...PARAMS, initialPrompt: ' ' });++ await settle();++ expect(hoisted.trackEvent).toHaveBeenCalledWith(+ 'session_started',+ expect.objectContaining({ has_initial_prompt: false })+ );+ });++ it('reports a session it only adopted apart from one started here', async () => {+ failWith('already-exists');++ await sessionService.createSession({ ...PARAMS, startSource: 'adopted' });++ await settle();++ expect(hoisted.trackEvent).toHaveBeenCalledWith(+ 'session_started',+ expect.objectContaining({ start_source: 'adopted' })+ );+ });++ it('reports nothing itself when the session starts', async () => {+ // The hook reports that one; reporting here as well would double-count it.+ hoisted.createSession.mockResolvedValue({+ success: true,+ data: { session: { id: 's-1', agentId: 'agent-1', providerId: 'codex' } },+ });++ await sessionService.createSession({ ...PARAMS });++ await settle();++ expect(hoisted.trackEvent).not.toHaveBeenCalled();+ });++ it('passes what the caller declared to the hook when the session does start', async () => {+ // The room flag only reaches a successful start this way, so asserting it+ // on a failure leaves the path every real session takes uncovered — and an+ // inverted flag looks the same from there.+ hoisted.createSession.mockResolvedValue({+ success: true,+ data: { session: { id: 's-1', agentId: 'agent-1', providerId: 'codex' } },+ });+ const created = vi.fn();+ const off = sessionService.on('session:created', created);++ await sessionService.createSession({ ...PARAMS, connectedToRoom: true });+ await settle();+ off();++ expect(created).toHaveBeenCalledWith(+ expect.objectContaining({ id: 's-1' }),+ expect.objectContaining({ connectedToRoom: true })+ );+ });+});++describe('provisioning a session again', () => {+ // Provisioning fails the way it does in the field: the session's row is+ // there, its agent's location is not open, and the service raises that+ // itself. Nothing here stands in for a step the service does not take.+ beforeEach(() => {+ hoisted.getSession.mockResolvedValue({+ id: 's-1',+ agentId: 'agent-1',+ providerId: 'codex',+ agentLocationId: 'loc',+ });+ hoisted.sessionRows.mockResolvedValue([{ id: 's-1', agentId: 'agent-1' }]);+ hoisted.mapSessionRow.mockReturnValue({+ id: 's-1',+ agentId: 'agent-1',+ providerId: 'codex',+ agentName: 'agent one',+ });+ hoisted.getLocation.mockReturnValue(undefined);+ });++ it('says nothing for a first attempt, which is not a retry', async () => {+ // Nearly every session is provisioned once. Counting those would bury the+ // thing worth knowing, which is whether a second attempt worked.+ await sessionService.provisionSession('s-1');+ await settle();++ expect(hoisted.trackEvent).not.toHaveBeenCalled();+ });++ it('separates a retry someone asked for from one the view made on its own', async () => {+ await sessionService.provisionSession('s-1', 'retry_button');+ await settle();+ await sessionService.provisionSession('s-1', 'auto');+ await settle();++ const triggers = hoisted.trackEvent.mock.calls+ .filter(([name]) => name === 'session_provision_retried')+ .map(([, p]) => (p as Record<string, unknown>).trigger);+ expect(triggers).toEqual(['retry_button', 'auto']);+ });++ it('reports a retry that failed rather than throwing it away', async () => {+ // The whole point: the failure used to be thrown, so nothing could report+ // it and the renderer's error branch was unreachable.+ await sessionService.provisionSession('s-1', 'retry_button');+ await settle();++ expect(hoisted.trackEvent).toHaveBeenCalledWith(+ 'session_provision_retried',+ expect.objectContaining({ outcome: 'failure', agent_type: 'codex', location: 'local' })+ );+ });++ it('hands the failure back as a value the caller can act on', async () => {+ const result = await sessionService.provisionSession('s-1', 'retry_button');+ await settle();++ expect(result.success).toBe(false);+ });++ it('never puts the failure message in the payload', async () => {+ // The message names the agent, because the person reading it has to know+ // which one to reopen. The agent is theirs and so is its name: the error+ // handed back to them is the only place it belongs.+ hoisted.mapSessionRow.mockReturnValue({+ id: 's-1',+ agentId: 'agent-1',+ providerId: 'codex',+ agentName: 'secret-project bot',+ });++ const result = await sessionService.provisionSession('s-1', 'auto');++ await settle();++ expect(JSON.stringify(result)).toContain('secret-project');+ expect(hoisted.trackEvent).toHaveBeenCalled();+ expect(JSON.stringify(hoisted.trackEvent.mock.calls)).not.toContain('secret-project');+ });+});diff --git a/console/apps/switch-console-desktop/src/main/core/sessions/session-service.ts b/console/apps/switch-console-desktop/src/main/core/sessions/session-service.tsindex 9d42d2001..5ec161fd6 100644--- a/console/apps/switch-console-desktop/src/main/core/sessions/session-service.ts+++ b/console/apps/switch-console-desktop/src/main/core/sessions/session-service.ts@@ -1,7 +1,12 @@-import { ok, type Result } from '@switch-console/shared';+import { err, ok, type Result } from '@switch-console/shared';import { eq, sql } from 'drizzle-orm';import { getAgentById } from '@main/core/agents/getAgentById';import { locationManager } from '@main/core/locations/location-manager';+import { agentTypeOf } from '@main/core/telemetry/agent-type';+import type { TelemetryOutcome, TelemetrySessionStartFailure } from '@main/core/telemetry/events';+import { entryPointOf, startSourceOf } from '@main/core/telemetry/narrow';+import { locationKindOf } from '@main/core/telemetry/shape';+import { trackEvent } from '@main/core/telemetry/telemetry-service';import { db } from '@main/db/client';import { sessions } from '@main/db/schema';import { events } from '@main/lib/events';@@ -19,16 +24,22 @@ import type {RenameSessionSuccess,Session,} from '@shared/core/sessions/sessions';+import type { SessionProvisionTrigger } from '@shared/core/telemetry/reporting';import { archiveSession } from './operations/archiveSession';import { createSession } from './operations/createSession';import { deleteSession } from './operations/deleteSession';import { ensureSessionAttachable } from './operations/ensureSessionAttachable';+import { getSession } from './operations/getSession';import { getSessions } from './operations/getSessions';import { renameSession } from './operations/renameSession';import { restoreSession } from './operations/restoreSession';import { setSessionPinned } from './operations/setSessionPinned';import { updateSessionStatus } from './operations/updateSessionStatus';-import type { TeardownSessionError } from './provision-session-error';+import {+ toProvisionError,+ type ProvisionSessionError,+ type TeardownSessionError,+} from './provision-session-error';import { provisionSessionRuntime, type SessionRuntimeResult } from './session-builder';import { sessionRuntimeManager } from './session-runtime-manager';import { mapSessionRowToSession } from './utils/utils';@@ -42,10 +53,80 @@ export type SessionLifecycleHooks = {'session:created': (session: Session, params: CreateSessionParams) => void | Promise<void>;'session:updated': (session: Session) => void | Promise<void>;'session:archived': (sessionId: string) => void | Promise<void>;+ /** An archived session was put back into use. The inverse of `archived`. */+ 'session:restored': (sessionId: string) => void | Promise<void>;'session:deleted': (sessionId: string) => void | Promise<void>;'session:runtime-ready': (sessionId: string, result: ProvisionResult) => void | Promise<void>;};+/** The error's discriminant as a reportable code. Never its message. */+const SESSION_START_FAILURE_REASON: Record<+ CreateSessionError['type'],+ TelemetrySessionStartFailure+> = {+ 'agent-not-found': 'agent_not_found',+ 'already-exists': 'already_exists',+ 'spawn-failed': 'spawn_failed',+};++/**+ * Report a session that did not start.+ *+ * At this call site rather than from a hook, because `session:created` fires+ * only when one did — which is exactly the blind spot. The agent is read back+ * to describe the attempt in the same terms as a success, so the two populations+ * are comparable; when it cannot be found, which is itself one of the failures,+ * the shape is honestly `unknown` rather than guessed.+ */+function reportFailedSessionStart(params: CreateSessionParams, error: CreateSessionError): void {+ // Not awaited: the reads that describe the attempt are ours, not the caller's,+ // and the person whose session failed should hear about it no later for our+ // having asked what kind it was.+ void (async () => {+ const agent = await getAgentById(params.agentId);++ trackEvent('session_started', {+ agent_type: agent ? agentTypeOf(agent.providerId) : 'unknown',+ location: agent ? await locationKindOf(agent.locationId) : 'unknown',+ outcome: 'failure',+ failure_reason: SESSION_START_FAILURE_REASON[error.type],+ entry_point: entryPointOf(params.entryPoint),+ start_source: startSourceOf(params.startSource),+ has_initial_prompt: (params.initialPrompt?.trim().length ?? 0) > 0,+ connected_to_room: params.connectedToRoom === true,+ });+ })().catch(() => {});+}++/**+ * Report a provision that was a retry.+ *+ * The first attempt for a session is not one, and reporting it would drown the+ * signal: nearly every session is provisioned once. The session is read back+ * for its shape, and reports `unknown` rather than a guess when it has gone —+ * which is one of the ways a provision fails.+ */+function reportProvisionRetry(+ sessionId: string,+ trigger: SessionProvisionTrigger,+ outcome: TelemetryOutcome+): void {+ if (trigger === 'initial') return;++ // Not awaited: this is two database reads on the path that hands a session+ // back to the person waiting for it.+ void (async () => {+ const session = await getSession(sessionId);+ const agent = session ? await getAgentById(session.agentId) : null;+ trackEvent('session_provision_retried', {+ agent_type: session ? agentTypeOf(session.providerId) : 'unknown',+ location: agent ? await locationKindOf(agent.locationId) : 'unknown',+ trigger,+ outcome,+ });+ })().catch(() => {});+}+/*** A session cannot start while its agent's location is closed. The condition is* a normal one — the user closed the agent — and is undone by reopening it, so@@ -72,6 +153,8 @@ export class SessionService implements Hookable<SessionLifecycleHooks> {const result = await createSession(params);if (result.success) {this.notifySessionCreated(result.data.session, params);+ } else {+ reportFailedSessionStart(params, result.error);}return result;}@@ -110,14 +193,38 @@ export class SessionService implements Hookable<SessionLifecycleHooks> {}}+ /**+ * Bring a session's runtime up, reporting the outcome rather than throwing it.+ *+ * It used to declare a `Result` and never return the error branch: every+ * failure threw, so the renderer's error branch was unreachable and the+ * rejection was swallowed by callers that could not act on it. A provision+ * that failed therefore left the session sitting on "setting up" with nothing+ * said. The failure is now a value, which is also the only way a retry can+ * report whether it worked.+ */async provisionSession(- sessionId: string- ): Promise<Result<ProvisionResult, TeardownSessionError>> {+ sessionId: string,+ trigger: SessionProvisionTrigger = 'initial'+ ): Promise<Result<ProvisionResult, ProvisionSessionError>> {+ try {+ const result = await this._provision(sessionId);+ reportProvisionRetry(sessionId, trigger, 'success');+ return ok(result);+ } catch (error) {+ reportProvisionRetry(sessionId, trigger, 'failure');+ return err(toProvisionError(error));+ }+ }++ private async _provision(sessionId: string): Promise<ProvisionResult> {const session = await this._loadSession(sessionId);const location = locationManager.getLocation(session.agentLocationId);// Recoverable in one click, so say which agent and what to do rather than// handing the user the location's id, which appears nowhere they can act on.- if (!location) throw new Error(notOpenMessage(session.session.agentName));+ if (!location) {+ throw { type: 'location-not-open', message: notOpenMessage(session.session.agentName) };+ }// Idempotency: session is already live — return current state.if (sessionRuntimeManager.getAgent(sessionId)) {@@ -128,7 +235,7 @@ export class SessionService implements Hookable<SessionLifecycleHooks> {await this._makeAttachable(sessionId);this._hooks.callHookBackground('session:runtime-ready', sessionId, provisionResult);events.emit(sessionProvisionedChannel, { sessionId, ...provisionResult });- return ok(provisionResult);+ return provisionResult;}const built = await provisionSessionRuntime(session.session, location);@@ -138,10 +245,10 @@ export class SessionService implements Hookable<SessionLifecycleHooks> {const provisionResult: ProvisionResult = { path: built.path, locationId: built.locationId };this._hooks.callHookBackground('session:runtime-ready', sessionId, provisionResult);events.emit(sessionProvisionedChannel, { sessionId, ...provisionResult });- return ok(provisionResult);+ return provisionResult;}- async launch(sessionId: string): Promise<Result<ProvisionResult, TeardownSessionError>> {+ async launch(sessionId: string): Promise<Result<ProvisionResult, ProvisionSessionError>> {return this.provisionSession(sessionId);}@@ -206,7 +313,9 @@ export class SessionService implements Hookable<SessionLifecycleHooks> {async restoreSession(id: string): Promise<void> {const session = await restoreSession(id);- if (session) this._hooks.callHookBackground('session:updated', session);+ if (!session) return;+ this._hooks.callHookBackground('session:updated', session);+ this._hooks.callHookBackground('session:restored', id);}async renameSession(diff --git a/console/apps/switch-console-desktop/src/main/core/settings/controller.telemetry.test.ts b/console/apps/switch-console-desktop/src/main/core/settings/controller.telemetry.test.tsnew file mode 100644index 000000000..2c8bb6acb--- /dev/null+++ b/console/apps/switch-console-desktop/src/main/core/settings/controller.telemetry.test.ts@@ -0,0 +1,142 @@+import { beforeEach, describe, expect, it, vi } from 'vitest';++/**+ * What changing a setting reports — and, for one setting, what it deliberately+ * does not.+ */++const { h } = vi.hoisted(() => ({+ h: {+ trackEvent: vi.fn(),+ get: vi.fn(),+ update: vi.fn(async () => {}),+ reset: vi.fn(async () => {}),+ resetField: vi.fn(async () => {}),+ },+}));++vi.mock('@main/core/telemetry/telemetry-service', () => ({ trackEvent: h.trackEvent }));+vi.mock('./settings-service', () => ({+ appSettingsService: {+ get: h.get,+ update: h.update,+ getAll: vi.fn(),+ getWithMeta: vi.fn(),+ reset: h.reset,+ resetField: h.resetField,+ },+}));++const { appSettingsController } = await import('./controller');++const NEVER_ASKED = { enabled: false, askedAt: null };++beforeEach(() => {+ vi.clearAllMocks();+ h.get.mockResolvedValue(NEVER_ASKED);+});++describe('changing a setting', () => {+ it('reports which setting changed, and never its value', async () => {+ await appSettingsController.update('terminal', {+ fontFamily: '/Users/someone/secret-project/font.ttf',+ } as never);++ expect(h.trackEvent).toHaveBeenCalledWith('setting_changed', { setting_key: 'terminal' });+ expect(JSON.stringify(h.trackEvent.mock.calls)).not.toContain('secret-project');+ });+});++describe('putting a setting back to its default', () => {+ it('reports a whole group being reset', async () => {+ await appSettingsController.reset('terminal');++ expect(h.trackEvent).toHaveBeenCalledWith('setting_changed', { setting_key: 'terminal' });+ });++ it('reports one field being reset', async () => {+ // The Reset control sits in the same rows the editors do. Counting only the+ // change that set a preference makes every one somebody undid look like one+ // that stuck.+ await appSettingsController.resetField('terminal', 'fontFamily');++ expect(h.trackEvent).toHaveBeenCalledWith('setting_changed', { setting_key: 'terminal' });+ });++ it('says nothing when the reset did not happen', async () => {+ h.reset.mockRejectedValueOnce(new Error('database is locked'));++ await expect(appSettingsController.reset('terminal')).rejects.toThrow();++ expect(h.trackEvent).not.toHaveBeenCalled();+ });++ it('does not treat resetting telemetry as an agreement to share usage data', async () => {+ // The default is off and never-asked, so a reset can only ever land on the+ // answer that has nothing to report.+ await appSettingsController.reset('telemetry');++ const names = h.trackEvent.mock.calls.map(([name]) => name);+ expect(names).toEqual(['setting_changed']);+ });+});++describe('agreeing to share usage data', () => {+ it('reports an agreement given at the first-run prompt', async () => {+ await appSettingsController.update('telemetry', { enabled: true, askedAt: 1 } as never);++ expect(h.trackEvent).toHaveBeenCalledWith('telemetry_consent_changed', {+ source: 'first_run',+ });+ });++ it('reports one given later, in settings, as that', async () => {+ h.get.mockResolvedValue({ enabled: false, askedAt: 1 });++ await appSettingsController.update('telemetry', { enabled: true, askedAt: 1 } as never);++ expect(h.trackEvent).toHaveBeenCalledWith('telemetry_consent_changed', { source: 'settings' });+ });++ it('says nothing when someone declines', async () => {+ // Not merely unreported — unreportable. The gate is read immediately before+ // every send, so this would be dropped anyway; the point is that we do not+ // try to transmit something from someone at the moment they said not to.+ await appSettingsController.update('telemetry', { enabled: false, askedAt: 1 } as never);++ const names = h.trackEvent.mock.calls.map(([name]) => name);+ expect(names).not.toContain('telemetry_consent_changed');+ });++ it('says nothing when consent is turned off again', async () => {+ h.get.mockResolvedValue({ enabled: true, askedAt: 1 });++ await appSettingsController.update('telemetry', { enabled: false, askedAt: 1 } as never);++ const names = h.trackEvent.mock.calls.map(([name]) => name);+ expect(names).not.toContain('telemetry_consent_changed');+ });++ it('does not report a fresh agreement when nothing changed', async () => {+ // Re-saving an unrelated part of the settings must not look like someone+ // agreeing all over again.+ h.get.mockResolvedValue({ enabled: true, askedAt: 1 });++ await appSettingsController.update('telemetry', { enabled: true, askedAt: 1 } as never);++ const names = h.trackEvent.mock.calls.map(([name]) => name);+ expect(names).not.toContain('telemetry_consent_changed');+ });++ it('writes the setting before reporting, since the gate is read on the way out', async () => {+ const order: string[] = [];+ h.update.mockImplementation(async () => void order.push('write'));+ h.trackEvent.mockImplementation((name: string) => {+ if (name === 'telemetry_consent_changed') order.push('report');+ });++ await appSettingsController.update('telemetry', { enabled: true, askedAt: 1 } as never);++ expect(order).toEqual(['write', 'report']);+ });+});diff --git a/console/apps/switch-console-desktop/src/main/core/settings/controller.ts b/console/apps/switch-console-desktop/src/main/core/settings/controller.tsindex 08882978f..99ab58fc9 100644--- a/console/apps/switch-console-desktop/src/main/core/settings/controller.ts+++ b/console/apps/switch-console-desktop/src/main/core/settings/controller.ts@@ -1,6 +1,31 @@+import type { TelemetrySettingKey } from '@main/core/telemetry/events';+import { trackEvent } from '@main/core/telemetry/telemetry-service';+import type { TelemetrySettings } from '@shared/core/app-settings';import { createRPCController } from '@shared/lib/ipc/rpc';import { appSettingsService, type AppSettings, type AppSettingsKey } from './settings-service';+/**+ * Report an agreement to share usage data, and only an agreement.+ *+ * Emitted after the write, which is the only order that can work: the gate is+ * read immediately before every send, so anything emitted before it would be+ * blocked by the very setting it is reporting. That also makes a refusal+ * unreportable, which is the intended outcome rather than a limitation to work+ * around — measuring someone at the moment they asked not to be measured is not+ * a thing to do because it is technically possible.+ *+ * Nothing is reported when the answer has not changed, so re-saving an unrelated+ * part of the settings does not look like a fresh agreement.+ */+function reportConsent(previous: TelemetrySettings, next: TelemetrySettings): void {+ if (!next.enabled || next.askedAt === null) return;+ if (previous.enabled && previous.askedAt !== null) return;++ trackEvent('telemetry_consent_changed', {+ source: previous.askedAt === null ? 'first_run' : 'settings',+ });+}+export const appSettingsController = createRPCController({get: <T extends AppSettingsKey>(key: T): Promise<AppSettings[T]> => appSettingsService.get(key),@@ -14,11 +39,43 @@ export const appSettingsController = createRPCController({overrides: Partial<AppSettings[T]>;}> => appSettingsService.getWithMeta(key),- update: <T extends AppSettingsKey>(key: T, value: AppSettings[T]): Promise<void> =>- appSettingsService.update(key, value),+ // Every setting change passes through this controller, so the key is reported+ // here rather than from each screen that offers one. The key only — several of+ // these values are free text.+ update: async <T extends AppSettingsKey>(key: T, value: AppSettings[T]): Promise<void> => {+ // Read before the write, because telling a first agreement from a later one+ // needs the old value — but never allowed to fail the write. This is the one+ // setting where a telemetry read blocking the write would stop someone+ // turning telemetry OFF, which is the last thing reporting may ever do.+ const previousTelemetry =+ key === 'telemetry' ? await appSettingsService.get('telemetry').catch(() => null) : null;++ await appSettingsService.update(key, value);++ trackEvent('setting_changed', { setting_key: key as TelemetrySettingKey });+ if (previousTelemetry) reportConsent(previousTelemetry, value as TelemetrySettings);+ },- reset: <T extends AppSettingsKey>(key: T): Promise<void> => appSettingsService.reset(key),+ /**+ * Put a whole settings group, or one field of it, back to its default.+ *+ * Reported under the same key as the change that set it, because reverting is+ * a person changing a setting: counting only the change would make every+ * preference somebody tried and undid look like one that stuck. The Reset+ * control sits in the same rows the editors do, so the two have to be+ * comparable.+ *+ * Resetting `telemetry` is not an agreement to share usage data and is not+ * reported as one. Its default is off and never-asked, so a reset can only+ * ever land on the answer that has nothing to report.+ */+ reset: async <T extends AppSettingsKey>(key: T): Promise<void> => {+ await appSettingsService.reset(key);+ trackEvent('setting_changed', { setting_key: key as TelemetrySettingKey });+ },- resetField: <T extends AppSettingsKey>(key: T, field: string): Promise<void> =>- appSettingsService.resetField(key, field as keyof AppSettings[T]),+ resetField: async <T extends AppSettingsKey>(key: T, field: string): Promise<void> => {+ await appSettingsService.resetField(key, field as keyof AppSettings[T]);+ trackEvent('setting_changed', { setting_key: key as TelemetrySettingKey });+ },});diff --git a/console/apps/switch-console-desktop/src/main/core/settings/schema.ts b/console/apps/switch-console-desktop/src/main/core/settings/schema.tsindex c0ac45b0b..43c45b234 100644--- a/console/apps/switch-console-desktop/src/main/core/settings/schema.ts+++ b/console/apps/switch-console-desktop/src/main/core/settings/schema.ts@@ -1,6 +1,7 @@import z from 'zod';import { BROWSER_ISOLATED_PROFILE_ID } from '@shared/browser';import { AGENT_PROVIDER_IDS } from '@shared/core/providers/agent-provider-registry';+import type { AppSettingsKeyName } from '@shared/core/settings/setting-keys';import {TERMINAL_FONT_SIZE_MAX,TERMINAL_FONT_SIZE_MIN,@@ -165,6 +166,22 @@ export const APP_SETTINGS_SCHEMA_MAP = {telemetry: telemetrySettingsSchema,} as const;+/**+ * The schema map and the shared list of setting names say the same thing.+ *+ * The list is what a setting change is reported against and cannot import this+ * file. Asserted both ways, so adding a group without naming it there — or+ * leaving a name behind after removing one — fails to compile.+ */+const _settingKeysAreExhaustive: AppSettingsKeyName extends keyof typeof APP_SETTINGS_SCHEMA_MAP+ ? true+ : never = true;+const _settingKeysAreComplete: keyof typeof APP_SETTINGS_SCHEMA_MAP extends AppSettingsKeyName+ ? true+ : never = true;+void _settingKeysAreExhaustive;+void _settingKeysAreComplete;+export const appSettingsSchema = z.object({localLocation: localLocationSettingsSchema,location: locationSettingsSchema,diff --git a/console/apps/switch-console-desktop/src/main/core/switch-rooms/auto-session-watcher.ts b/console/apps/switch-console-desktop/src/main/core/switch-rooms/auto-session-watcher.tsindex 5ee20ea58..14fd7e120 100644--- a/console/apps/switch-console-desktop/src/main/core/switch-rooms/auto-session-watcher.ts+++ b/console/apps/switch-console-desktop/src/main/core/switch-rooms/auto-session-watcher.ts@@ -10,6 +10,7 @@ import {SWITCH_SUBAGENTS_DIR_RELATIVE,} from '@main/core/agents/switch-settings-paths';import { getLocationById } from '@main/core/locations/store';+import { formatProvisionSessionError } from '@main/core/sessions/provision-session-error';import { sessionService } from '@main/core/sessions/session-service';import { fetchRoomDetail } from '@main/core/switch-servers/gateway-client';import { getServer } from '@main/core/switch-servers/servers-store';@@ -685,6 +686,11 @@ class AutoSessionWatcher {? `connect to switch room ${roomId}`: `connect to switch room ${roomId}\n\nThen respond to this, which is what you were started for:\n${triggerLine}`,autoApprove,+ // Nobody is in the desktop app: the app started this session on the+ // user's behalf, and only because of a message in the room it is+ // about to connect to.+ startSource: 'auto',+ connectedToRoom: true,});if (result.success) {log.info('AutoSessionWatcher: spawned session for room', {@@ -699,13 +705,16 @@ class AutoSessionWatcher {// (it never reconciles to ready). provisionSession is idempotent// (fast-paths on the already-registered runtime) and emits the// provisioned event the renderer needs.- await sessionService.provisionSession(result.data.session.id).catch((error) => {+ // The failure is a value now, not a rejection: a `.catch` here would+ // never run and the failure would pass in silence.+ const provisioned = await sessionService.provisionSession(result.data.session.id);+ if (!provisioned.success) {log.warn('AutoSessionWatcher: post-spawn provision-reconcile failed', {roomId,sessionId: result.data.session.id,- error: String(error),+ error: formatProvisionSessionError(provisioned.error),});- });+ }return;}lastError = JSON.stringify(result.error);diff --git a/console/apps/switch-console-desktop/src/main/core/switch-rooms/restore-sessions.test.ts b/console/apps/switch-console-desktop/src/main/core/switch-rooms/restore-sessions.test.tsindex 93fd6ed0b..e0070bb64 100644--- a/console/apps/switch-console-desktop/src/main/core/switch-rooms/restore-sessions.test.ts+++ b/console/apps/switch-console-desktop/src/main/core/switch-rooms/restore-sessions.test.ts@@ -6,12 +6,24 @@ const loadSessionWithAgent = vi.hoisted(() => vi.fn());const getLocationById = vi.hoisted(() => vi.fn());const getLocation = vi.hoisted(() => vi.fn(() => ({}) as unknown));const openLocation = vi.hoisted(() => vi.fn(async () => ({ success: true })));-const provisionSession = vi.hoisted(() => vi.fn<(id: string) => Promise<void>>(async () => {}));+/**+ * Provisioning reports its failures as a value rather than throwing, so the+ * double has to answer with one — a bare `undefined` reads as a failure and+ * would skip every session.+ */+const provisionSession = vi.hoisted(() =>+ vi.fn<(id: string) => Promise<{ success: boolean; error?: unknown; data?: unknown }>>(+ async () => ({ success: true, data: { path: '/repo', locationId: 'loc-1' } })+ )+);const hydrateSession = vi.hoisted(() => vi.fn<(id: string) => Promise<void>>(async () => {}));const ensureSessionAttachable = vi.hoisted(() =>vi.fn<(id: string) => Promise<boolean>>(async () => false));+// Naming the provision failure pulls in the error module, which reaches the+// database through the runtime manager at import time.+vi.mock('@main/db/client', () => ({ db: {} }));vi.mock('./switch-room-service', () => ({switchRoomService: { listPersistedSessionIds, prunePersisted },}));@@ -106,9 +118,11 @@ describe('restoreSwitchRoomSessions', () => {it('keeps going when one session fails to restore', async () => {listPersistedSessionIds.mockResolvedValue(['bad-1', 'good-1']);- provisionSession.mockImplementation(async (id: string) => {- if (id === 'bad-1') throw new Error('provision blew up');- });+ provisionSession.mockImplementation(async (id: string) =>+ id === 'bad-1'+ ? { success: false, error: { type: 'error', message: 'provision blew up' } }+ : { success: true, data: { path: '/repo', locationId: 'loc-1' } }+ );ensureSessionAttachable.mockResolvedValue(true);await restoreSwitchRoomSessions();diff --git a/console/apps/switch-console-desktop/src/main/core/switch-rooms/restore-sessions.ts b/console/apps/switch-console-desktop/src/main/core/switch-rooms/restore-sessions.tsindex ccca26378..9c0abc2b4 100644--- a/console/apps/switch-console-desktop/src/main/core/switch-rooms/restore-sessions.ts+++ b/console/apps/switch-console-desktop/src/main/core/switch-rooms/restore-sessions.ts@@ -2,6 +2,7 @@ import { locationManager } from '@main/core/locations/location-manager';import { getLocationById } from '@main/core/locations/store';import { ensureSessionAttachable } from '@main/core/sessions/operations/ensureSessionAttachable';import { hydrateSession } from '@main/core/sessions/operations/hydrateSession';+import { formatProvisionSessionError } from '@main/core/sessions/provision-session-error';import { loadSessionWithAgent } from '@main/core/sessions/session-join';import { sessionService } from '@main/core/sessions/session-service';import { log } from '@main/lib/logger';@@ -77,7 +78,17 @@ export async function restoreSwitchRoomSessions(): Promise<void> {}}- await sessionService.provisionSession(sessionId);+ // Say why, in its own terms. Letting it fall through to the attach below+ // reports whatever that fails with instead, which is a different and less+ // useful sentence — "session not found" rather than "its agent is closed".+ const provisioned = await sessionService.provisionSession(sessionId);+ if (!provisioned.success) {+ log.warn('restoreSwitchRoomSessions: could not provision a restored session', {+ sessionId,+ error: formatProvisionSessionError(provisioned.error),+ });+ continue;+ }if (await ensureSessionAttachable(sessionId)) {attachable += 1;} else {diff --git a/console/apps/switch-console-desktop/src/main/core/switch-servers/controller.test.ts b/console/apps/switch-console-desktop/src/main/core/switch-servers/controller.test.tsindex f00fc8b96..44875ad81 100644--- a/console/apps/switch-console-desktop/src/main/core/switch-servers/controller.test.ts+++ b/console/apps/switch-console-desktop/src/main/core/switch-servers/controller.test.ts@@ -1,16 +1,28 @@import { beforeEach, describe, expect, it, vi } from 'vitest';+import { HostUnreachableError } from '@shared/core/remote-hosts/reachability';const fetchMe = vi.hoisted(() => vi.fn());const getServer = vi.hoisted(() => vi.fn());const isManagedServerRunning = vi.hoisted(() => vi.fn());const managedServerHostBlocked = vi.hoisted(() => vi.fn((): unknown => null));const fetchAuthConfig = vi.hoisted(() => vi.fn());+const trackEvent = vi.hoisted(() => vi.fn());+const addServer = vi.hoisted(() => vi.fn());+const resolveAgentServers = vi.hoisted(() => vi.fn());+const passwordLogin = vi.hoisted(() => vi.fn());+const createRoomOnServer = vi.hoisted(() => vi.fn());+const deleteBridge = vi.hoisted(() => vi.fn());+const deleteRoom = vi.hoisted(() => vi.fn());+const fetchBridges = vi.hoisted(() => vi.fn());+// Stubbed rather than reimplemented: what the tests below assert is that the+// kind reaches the event, not how a row is read as one.+const serverKindOf = vi.hoisted(() => vi.fn(() => 'remote_managed'));// Stub the modules the controller imports that would otherwise pull electron /-// ssh / agent side effects at load. We only exercise getConnectionStatus.+// ssh / agent side effects at load.vi.mock('@main/core/agents/agent-defaults', () => ({ suggestAgentDefaults: vi.fn() }));vi.mock('@main/core/agents/propagate-server-api-url', () => ({ propagateServerApiUrl: vi.fn() }));-vi.mock('@main/core/agents/resolve-servers', () => ({ resolveAgentServers: vi.fn() }));+vi.mock('@main/core/agents/resolve-servers', () => ({ resolveAgentServers }));vi.mock('@main/core/agents/write-remote-switch-settings', () => ({writeRemoteSwitchSettings: vi.fn(),}));@@ -19,23 +31,32 @@ vi.mock('@main/core/app/service', () => ({ appService: { openExternal: vi.fn() }vi.mock('@main/core/fs/impl/ssh-fs', () => ({ SshFileSystem: vi.fn() }));vi.mock('@main/core/locations/location-transport', () => ({ sshConnectionIdForHost: vi.fn() }));vi.mock('@main/core/ssh/connect/connect-agent-ssh', () => ({ ensureSshConnected: vi.fn() }));+vi.mock('@main/core/telemetry/telemetry-service', () => ({ trackEvent }));vi.mock('@main/core/managed-switch-server/managed-server-status', () => ({isManagedServerRunning,managedServerHostBlocked,}));-vi.mock('./auth', () => ({ oidcLogin: vi.fn(), passwordLogin: vi.fn() }));+// Writes to the app's log file, which a test has no business creating.+vi.mock('@main/lib/logger', () => ({+ log: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },+}));+vi.mock('./auth', () => ({ oidcLogin: vi.fn(), passwordLogin }));// Reads this install's own agent rows, and through them the database client.vi.mock('./backfill-agent-icons', () => ({ backfillAgentIcons: vi.fn() }));// Reaches the encrypted secrets store, and through it the database client.vi.mock('./bundled-chat-sign-in', () => ({ bundledChatSignInFor: vi.fn() }));+vi.mock('./create-room', () => ({ createRoomOnServer }));vi.mock('./gateway-web', () => ({ openAuthenticatedGatewayPage: vi.fn() }));vi.mock('./gateway-client', () => ({fetchMe,agentExistsOnServer: vi.fn(),+ deleteBridge,+ deleteRoom,fetchAgentDetail: vi.fn(),fetchAgentRooms: vi.fn(),fetchAgents: vi.fn(),fetchAuthConfig,+ fetchBridges,fetchRoomRoles: vi.fn(),fetchRooms: vi.fn(),registerKnownAgent: vi.fn(),@@ -43,12 +64,13 @@ vi.mock('./gateway-client', () => ({}));vi.mock('./servers-store', () => ({getServer,- addServer: vi.fn(),+ addServer,deleteSessionCookie: vi.fn(),getActiveServerId: vi.fn(),listServers: vi.fn(),removeServer: vi.fn(),renameServer: vi.fn(),+ serverKindOf,setActiveServerId: vi.fn(),updateServer: vi.fn(),}));@@ -132,3 +154,165 @@ describe('gateway calls on an unreachable host', () => {expect(fetchAuthConfig).toHaveBeenCalledOnce();});});++describe('disconnecting a bridge', () => {+ beforeEach(() => {+ vi.clearAllMocks();+ managedServerHostBlocked.mockReturnValue(null);+ getServer.mockResolvedValue(server({}));+ fetchBridges.mockResolvedValue([{ id: 'b1', type: 'slack' }]);+ });++ it('reports a disconnection the gateway carried out', async () => {+ deleteBridge.mockResolvedValue({ kind: 'deleted' });++ await switchServersController.deleteBridge({ serverId: 'srv', bridgeId: 'b1' });++ await vi.waitFor(() =>+ expect(trackEvent).toHaveBeenCalledWith('bridge_disconnected', {+ bridge_platform: 'slack',+ outcome: 'success',+ })+ );+ });++ it('reports a refusal as a failure rather than as a disconnection', async () => {+ // Admin-only, and the gateway hands back the refusal instead of throwing+ // it — so the await returns exactly as it does for a bridge that went.+ deleteBridge.mockResolvedValue({ kind: 'forbidden' });++ await switchServersController.deleteBridge({ serverId: 'srv', bridgeId: 'b1' });++ await vi.waitFor(() =>+ expect(trackEvent).toHaveBeenCalledWith('bridge_disconnected', {+ bridge_platform: 'slack',+ outcome: 'failure',+ })+ );+ });+});++describe('an action a server whose host has gone down cannot take', () => {+ const blocked = {+ sshHost: 'h',+ status: 'unreachable',+ lastError: 'no route to host',+ lastCheckedAt: null,+ };++ beforeEach(() => {+ vi.clearAllMocks();+ getServer.mockResolvedValue(server({ managed: true, managementKind: 'remote', sshHost: 'h' }));+ managedServerHostBlocked.mockReturnValue(blocked);+ // What the gateway does on a host that cannot be reached: the platform is+ // then unknowable rather than absent.+ fetchBridges.mockRejectedValue(new Error('no route to host'));+ });++ it('reports the room it refused to create', async () => {+ await expect(+ switchServersController.createRoom({+ serverId: 'srv',+ name: 'Room',+ description: '',+ bridgeId: 'b1',+ agentIds: ['a1'],+ })+ ).rejects.toBeInstanceOf(HostUnreachableError);++ expect(createRoomOnServer).not.toHaveBeenCalled();+ await vi.waitFor(() =>+ expect(trackEvent).toHaveBeenCalledWith('room_created', {+ server_kind: 'remote_managed',+ bridge_platform: 'unknown',+ agent_count: 1,+ has_instructions: false,+ outcome: 'failure',+ failure_reason: 'unreachable',+ })+ );+ });++ it('reports the room it refused to delete', async () => {+ await expect(+ switchServersController.deleteRoom({ serverId: 'srv', roomId: 'r1' })+ ).rejects.toBeInstanceOf(HostUnreachableError);++ expect(deleteRoom).not.toHaveBeenCalled();+ expect(trackEvent).toHaveBeenCalledWith('room_deleted', {+ server_kind: 'remote_managed',+ outcome: 'failure',+ });+ });++ it('reports the sign-in that never left this machine', async () => {+ await expect(+ switchServersController.passwordLogin({+ serverId: 'srv',+ email: '[email protected]',+ password: 'hunter2',+ })+ ).rejects.toBeInstanceOf(HostUnreachableError);++ expect(passwordLogin).not.toHaveBeenCalled();+ expect(trackEvent).toHaveBeenCalledWith('server_sign_in', {+ auth_method: 'password',+ server_kind: 'remote_managed',+ outcome: 'failure',+ failure_reason: 'unreachable',+ });+ });++ it('still reports a sign-in by its own reason while the host is up', async () => {+ managedServerHostBlocked.mockReturnValue(null);+ passwordLogin.mockResolvedValue({ success: false, error: { kind: 'invalid_credentials' } });++ await switchServersController.passwordLogin({+ serverId: 'srv',+ email: '[email protected]',+ password: 'hunter2',+ });++ expect(trackEvent).toHaveBeenCalledWith('server_sign_in', {+ auth_method: 'password',+ server_kind: 'remote_managed',+ outcome: 'failure',+ failure_reason: 'invalid_credentials',+ });+ });+});++describe('adding a server by URL', () => {+ const params = { name: 'S', gatewayUrl: 'http://gateway', apiUrl: 'http://api' };++ beforeEach(() => {+ vi.clearAllMocks();+ resolveAgentServers.mockResolvedValue(undefined);+ });++ it('keeps the add that worked when reconciling the agent links does not', async () => {+ // The row is in; unlinking agents from servers that are gone is bookkeeping+ // after the fact. Rejecting here would show the user a failure for a server+ // they now have, and a second press would register it twice.+ const added = server({ id: 'new' });+ addServer.mockResolvedValue(added);+ resolveAgentServers.mockRejectedValue(new Error('database is locked'));++ await expect(switchServersController.addServer(params)).resolves.toBe(added);+ expect(trackEvent).toHaveBeenCalledExactlyOnceWith('server_added', {+ server_kind: 'external',+ outcome: 'success',+ });+ });++ it('reports the failure when the row itself cannot be written', async () => {+ addServer.mockRejectedValue(new Error('constraint failed'));++ await expect(switchServersController.addServer(params)).rejects.toThrow('constraint failed');+ expect(trackEvent).toHaveBeenCalledTimes(1);+ expect(trackEvent).toHaveBeenCalledWith('server_added', {+ server_kind: 'external',+ outcome: 'failure',+ });+ });+});diff --git a/console/apps/switch-console-desktop/src/main/core/switch-servers/controller.ts b/console/apps/switch-console-desktop/src/main/core/switch-servers/controller.tsindex 75c4a9785..f3bb0cdbd 100644--- a/console/apps/switch-console-desktop/src/main/core/switch-servers/controller.ts+++ b/console/apps/switch-console-desktop/src/main/core/switch-servers/controller.ts@@ -19,6 +19,20 @@ import {managedServerHostBlocked,} from '@main/core/managed-switch-server/managed-server-status';import { ensureSshConnected } from '@main/core/ssh/connect/connect-agent-ssh';+import { bridgePlatformOfType } from '@main/core/telemetry/bridge-platform';+import type {+ TelemetryAuthMethod,+ TelemetryBridgeFailure,+ TelemetryBridgePlatform,+ TelemetryOutcome,+ TelemetryRoomAgentsDirection,+ TelemetryRoomCreateFailure,+ TelemetryServerKind,+ TelemetrySignInFailure,+} from '@main/core/telemetry/events';+import { roomAgentsDirectionOf } from '@main/core/telemetry/narrow';+import { trackEvent } from '@main/core/telemetry/telemetry-service';+import { log } from '@main/lib/logger';import { agentAvatarUrlForName } from '@shared/core/agents/agent-avatar';import type { AgentProviderId } from '@shared/core/providers/agent-provider-registry';import { HostUnreachableError } from '@shared/core/remote-hosts/reachability';@@ -109,6 +123,7 @@ import {renameServer,setActiveServerId,updateServer,+ serverKindOf,} from './servers-store';import { updateBridgeOnServer } from './update-bridge';@@ -120,6 +135,19 @@ async function requireServer(serverId: string): Promise<SwitchServer> {return server;}+/**+ * The refusal a managed server's host being down produces, or null while it is+ * up.+ *+ * Returned rather than thrown so a path that reports its own outcome can count+ * the refusal before it propagates: the server is what an event describes+ * itself with, and a helper that throws leaves the caller holding nothing.+ */+function hostUnreachable(server: SwitchServer): HostUnreachableError | null {+ const blocked = managedServerHostBlocked(server);+ return blocked ? new HostUnreachableError(blocked) : null;+}+/*** Resolve a server and refuse to touch its gateway while the host it is managed* on is unreachable (CHOO-1780). `gatewayFetch` enforces the same rule at the@@ -129,17 +157,154 @@ async function requireServer(serverId: string): Promise<SwitchServer> {*/async function requireReachableServer(serverId: string): Promise<SwitchServer> {const server = await requireServer(serverId);- const blocked = managedServerHostBlocked(server);- if (blocked) throw new HostUnreachableError(blocked);+ const unreachable = hostUnreachable(server);+ if (unreachable) throw unreachable;return server;}+/** A bridge result's discriminant as a code. Never the message beside it. */+function bridgeFailureReason(kind: string): TelemetryBridgeFailure {+ switch (kind) {+ case 'created':+ return 'none';+ case 'unauthenticated':+ return 'unauthenticated';+ case 'forbidden':+ return 'forbidden';+ case 'invalid':+ return 'invalid';+ default:+ return 'error';+ }+}++/** A sign-in's own error union, as a reportable code. Never its message. */+const SIGN_IN_FAILURE: Record<LoginError['kind'], TelemetrySignInFailure> = {+ invalid_credentials: 'invalid_credentials',+ cancelled: 'cancelled',+ failed: 'failed',+};++function signInFailureReason(result: Result<unknown, LoginError>): TelemetrySignInFailure {+ return result.success ? 'none' : SIGN_IN_FAILURE[result.error.kind];+}++/**+ * Reported by reason rather than by outcome: the two are the same fact, and a+ * sign-in that never left this machine — the server's host is down — has a+ * reason of its own but no result to read one from.+ */+function reportSignIn(+ method: TelemetryAuthMethod,+ server: SwitchServer,+ failureReason: TelemetrySignInFailure+): void {+ trackEvent('server_sign_in', {+ auth_method: method,+ server_kind: serverKindOf(server),+ outcome: failureReason === 'none' ? 'success' : 'failure',+ failure_reason: failureReason,+ });+}++/** A room-create result's discriminant as a code. */+function roomCreateFailureReason(result: CreateRoomResult): TelemetryRoomCreateFailure {+ switch (result.kind) {+ case 'created':+ return 'none';+ case 'unauthenticated':+ return 'unauthenticated';+ case 'bridge-unavailable':+ return 'bridge_unavailable';+ case 'invalid':+ return 'invalid';+ default:+ return 'error';+ }+}++/**+ * Which platform a bridge id is on.+ *+ * A lookup rather than a field: these operations take a bridge id, and the type+ * either never appears (a delete) or appears only on success (a room). Best+ * effort — an unreachable server yields `unknown` rather than failing the+ * operation it is only describing.+ *+ * **Never awaited by a caller doing real work.** It asks the gateway, and making+ * someone wait on a network round trip so we can describe what they did would+ * put reporting in the path of the thing being reported. `reportWithBridge` is+ * how the answer is used once it arrives.+ */+function bridgePlatformOf(+ server: SwitchServer,+ bridgeId: string | null | undefined+): Promise<TelemetryBridgePlatform> {+ if (!bridgeId) return Promise.resolve('unknown');+ return fetchBridges(server)+ .then((bridges) => bridgePlatformOfType(bridges.find((b) => b.id === bridgeId)?.type))+ .catch((): TelemetryBridgePlatform => 'unknown');+}++/**+ * Report once the platform is known, without anyone waiting for it.+ *+ * The event arrives a moment after the action rather than with it, which costs+ * nothing: it carries its own timestamp, taken when the work happened.+ */+function reportWithBridge(+ platform: Promise<TelemetryBridgePlatform>,+ emit: (platform: TelemetryBridgePlatform) => void+): void {+ void platform.then(emit).catch(() => {});+}++/** The same, for a room create whose other properties are already known. */+function reportRoomCreated(+ server: SwitchServer,+ bridgeId: string | null | undefined,+ rest: {+ server_kind: TelemetryServerKind;+ agent_count: number;+ has_instructions: boolean;+ failure_reason: TelemetryRoomCreateFailure;+ }+): void {+ reportWithBridge(bridgePlatformOf(server, bridgeId), (bridge_platform) =>+ trackEvent('room_created', {+ ...rest,+ bridge_platform,+ outcome: rest.failure_reason === 'none' ? 'success' : 'failure',+ })+ );+}+export const switchServersController = createRPCController({listServers: (): Promise<SwitchServer[]> => listServers(),+ // Both outcomes are reported here rather than the success at the store's+ // insert, so that one press of Add produces exactly one event whichever way+ // it goes. Reported on the insert, because that is the whole of the action:+ // registering a URL is a row, and everything after it is bookkeeping.addServer: async (params: AddServerParams): Promise<SwitchServer> => {- const server = await addServer(params);- await resolveAgentServers();+ let server: SwitchServer;+ try {+ server = await addServer(params);+ } catch (error) {+ trackEvent('server_added', { server_kind: 'external', outcome: 'failure' });+ throw error;+ }+ trackEvent('server_added', { server_kind: 'external', outcome: 'success' });+ // The row has landed, so the server is added whatever happens next — this+ // reconciliation only unlinks agents pointing at servers that are gone.+ // Rejecting for it would tell the user their add failed while the store has+ // already reported it as done, and leave them to press Add again, which+ // registers the same server a second time rather than retrying the first.+ try {+ await resolveAgentServers();+ } catch (error) {+ log.warn('switch-servers: could not reconcile agent links after adding a server', { error });+ }return server;},@@ -171,15 +336,40 @@ export const switchServersController = createRPCController({getAuthConfig: async (serverId: string): Promise<SwitchAuthConfig> =>fetchAuthConfig(await requireReachableServer(serverId)),+ // Reported here rather than in `auth.ts`: the same functions are used to+ // re-authenticate a managed server on its own and to log in while starting a+ // stack, and neither of those is a person signing in.passwordLogin: async (params: PasswordLoginParams) => {- const server = await requireReachableServer(params.serverId);- return passwordLogin(server, params.email, params.password);+ const server = await requireServer(params.serverId);+ const unreachable = hostUnreachable(server);+ if (unreachable) {+ reportSignIn('password', server, 'unreachable');+ throw unreachable;+ }+ const result = await passwordLogin(server, params.email, params.password);+ reportSignIn('password', server, signInFailureReason(result));+ return result;},- oidcLogin: async (serverId: string): Promise<Result<true, LoginError>> =>- oidcLogin(await requireReachableServer(serverId)),+ oidcLogin: async (serverId: string): Promise<Result<true, LoginError>> => {+ const server = await requireServer(serverId);+ const unreachable = hostUnreachable(server);+ if (unreachable) {+ reportSignIn('oidc', server, 'unreachable');+ throw unreachable;+ }+ const result = await oidcLogin(server);+ reportSignIn('oidc', server, signInFailureReason(result));+ return result;+ },- logout: (serverId: string): Promise<void> => deleteSessionCookie(serverId),+ logout: async (serverId: string): Promise<void> => {+ // Read before the cookie goes, so the kind of server is still knowable — and+ // caught, because nobody should be unable to sign out because of it.+ const server = await getServer(serverId).catch(() => null);+ await deleteSessionCookie(serverId);+ if (server) trackEvent('server_sign_out', { server_kind: serverKindOf(server) });+ },/*** Open a gateway web page (operator dashboard). For the managed local server —@@ -259,13 +449,30 @@ export const switchServersController = createRPCController({*/createBridge: async (params: CreateBridgeParams): Promise<CreateBridgeResult> => {const server = await requireReachableServer(params.serverId);- return createBridgeOnServer(server, {- bridgeType: params.bridgeType,- displayName: params.displayName,- connectionConfig: params.connectionConfig,- setAsDefault: params.setAsDefault,- channelCreationEnabled: params.channelCreationEnabled,+ const platform = bridgePlatformOfType(params.bridgeType);+ let result: CreateBridgeResult;+ try {+ result = await createBridgeOnServer(server, {+ bridgeType: params.bridgeType,+ displayName: params.displayName,+ connectionConfig: params.connectionConfig,+ setAsDefault: params.setAsDefault,+ channelCreationEnabled: params.channelCreationEnabled,+ });+ } catch (error) {+ trackEvent('bridge_connected', {+ bridge_platform: platform,+ outcome: 'failure',+ failure_reason: 'error',+ });+ throw error;+ }+ trackEvent('bridge_connected', {+ bridge_platform: platform,+ outcome: result.kind === 'created' ? 'success' : 'failure',+ failure_reason: bridgeFailureReason(result.kind),});+ return result;},/**@@ -287,8 +494,20 @@ export const switchServersController = createRPCController({* `deleteBridge`. The renderer owns the confirmation; by the time this runs* the rooms are being given up deliberately.*/- deleteBridge: async (params: DeleteBridgeParams): Promise<DeleteBridgeResult> =>- deleteBridge(await requireReachableServer(params.serverId), params.bridgeId),+ deleteBridge: async (params: DeleteBridgeParams): Promise<DeleteBridgeResult> => {+ const server = await requireReachableServer(params.serverId);+ // Started before the delete, because afterwards there is no bridge left to+ // read a platform from — but never waited on: see `reportWithBridge`.+ const platform = bridgePlatformOf(server, params.bridgeId);+ const result = await deleteBridge(server, params.bridgeId);+ reportWithBridge(platform, (bridge_platform) =>+ trackEvent('bridge_disconnected', {+ bridge_platform,+ outcome: result.kind === 'deleted' ? 'success' : 'failure',+ })+ );+ return result;+ },/*** Create a room on the chosen server, owned by the signed-in user. Room@@ -296,14 +515,37 @@ export const switchServersController = createRPCController({* recoverable failures onto a typed result the modal can act on.*/createRoom: async (params: CreateRoomParams): Promise<CreateRoomResult> => {- const server = await requireReachableServer(params.serverId);- return createRoomOnServer(server, {- name: params.name,- description: params.description,- instructions: params.instructions,- bridgeId: params.bridgeId,- agentIds: params.agentIds,- });+ const server = await requireServer(params.serverId);+ const report = (failure_reason: TelemetryRoomCreateFailure) =>+ reportRoomCreated(server, params.bridgeId, {+ server_kind: serverKindOf(server),+ agent_count: params.agentIds.length,+ has_instructions: (params.instructions?.trim().length ?? 0) > 0,+ failure_reason,+ });++ const unreachable = hostUnreachable(server);+ if (unreachable) {+ report('unreachable');+ throw unreachable;+ }++ let result: CreateRoomResult;+ try {+ result = await createRoomOnServer(server, {+ name: params.name,+ description: params.description,+ instructions: params.instructions,+ bridgeId: params.bridgeId,+ agentIds: params.agentIds,+ });+ } catch (error) {+ report('error');+ throw error;+ }++ report(roomCreateFailureReason(result));+ return result;},listAgentRooms: async (params: {@@ -342,8 +584,24 @@ export const switchServersController = createRPCController({serverId: string;roomId: string;agentIds: string[];- }): Promise<void> =>- addRoomAgents(await requireReachableServer(params.serverId), params.roomId, params.agentIds),+ /**+ * Which screen this came from. The same call serves both, and the+ * one-agent-to-many-rooms screen loops it once per room — so without this,+ * adding an agent to five rooms is indistinguishable from five people each+ * adding one agent.+ */+ direction: TelemetryRoomAgentsDirection;+ }): Promise<void> => {+ await addRoomAgents(+ await requireReachableServer(params.serverId),+ params.roomId,+ params.agentIds+ );+ trackEvent('room_agents_added', {+ agent_count: params.agentIds.length,+ direction: roomAgentsDirectionOf(params.direction),+ });+ },/** Remove one agent from a room. Membership only — the agent is not deleted. */removeRoomAgent: async (params: {@@ -354,8 +612,27 @@ export const switchServersController = createRPCController({removeRoomAgent(await requireReachableServer(params.serverId), params.roomId, params.agentId),/** Delete a room and everything in it. The gateway enforces who may. */- deleteRoom: async (params: { serverId: string; roomId: string }): Promise<void> =>- deleteRoom(await requireReachableServer(params.serverId), params.roomId),+ deleteRoom: async (params: { serverId: string; roomId: string }): Promise<void> => {+ const server = await requireServer(params.serverId);+ const report = (outcome: TelemetryOutcome) =>+ trackEvent('room_deleted', { server_kind: serverKindOf(server), outcome });++ // A host that has gone down refuses the deletion as surely as the gateway+ // can, and the event has an outcome precisely so a refusal is counted.+ const unreachable = hostUnreachable(server);+ if (unreachable) {+ report('failure');+ throw unreachable;+ }++ try {+ await deleteRoom(server, params.roomId);+ } catch (error) {+ report('failure');+ throw error;+ }+ report('success');+ },listRemoteRoomGroups: async (serverId: string): Promise<RemoteRoomGroup[]> =>fetchRoomGroups(await requireServer(serverId)),@@ -379,12 +656,21 @@ export const switchServersController = createRPCController({),/** Claim a messaging-app account as the signed-in Switch user's own. */- claimBridgeIdentity: async (params: ClaimIdentityParams): Promise<ClaimIdentityResult> =>- claimIdentityOnServer(await requireReachableServer(params.serverId), {+ claimBridgeIdentity: async (params: ClaimIdentityParams): Promise<ClaimIdentityResult> => {+ const server = await requireReachableServer(params.serverId);+ const result = await claimIdentityOnServer(server, {bridgeId: params.bridgeId,externalUserId: params.externalUserId,username: params.username,- }),+ });+ reportWithBridge(bridgePlatformOf(server, params.bridgeId), (bridge_platform) =>+ trackEvent('bridge_identity_claimed', {+ bridge_platform,+ outcome: result.kind === 'claimed' ? 'success' : 'failure',+ })+ );+ return result;+ },/** Give up a claim on a messaging-app account, leaving any other user's claim* on it in place. `userId` is whose claim to drop — null for the signed-indiff --git a/console/apps/switch-console-desktop/src/main/core/switch-servers/delete-server-agents.db.test.ts b/console/apps/switch-console-desktop/src/main/core/switch-servers/delete-server-agents.db.test.tsindex 5243a6514..b38f92171 100644--- a/console/apps/switch-console-desktop/src/main/core/switch-servers/delete-server-agents.db.test.ts+++ b/console/apps/switch-console-desktop/src/main/core/switch-servers/delete-server-agents.db.test.ts@@ -80,7 +80,11 @@ describe('deleteAgentsForServer', () => {await deleteAgentsForServer('managed-1');- expect(mocks.deleteAgent).toHaveBeenCalledWith('agent-a', { deleteInSwitch: false });+ expect(mocks.deleteAgent).toHaveBeenCalledWith('agent-a', {+ deleteInSwitch: false,+ // Wiping a server is one action, not a person deleting each agent.+ trigger: 'server_teardown',+ });});it('reports a failed agent instead of stranding the rest', async () => {diff --git a/console/apps/switch-console-desktop/src/main/core/switch-servers/delete-server-agents.ts b/console/apps/switch-console-desktop/src/main/core/switch-servers/delete-server-agents.tsindex 7d5fcdb6f..2a3ebd6e1 100644--- a/console/apps/switch-console-desktop/src/main/core/switch-servers/delete-server-agents.ts+++ b/console/apps/switch-console-desktop/src/main/core/switch-servers/delete-server-agents.ts@@ -40,7 +40,7 @@ export async function deleteAgentsForServer(for (const row of rows) {try {- await deleteAgent(row.id, { deleteInSwitch: false });+ await deleteAgent(row.id, { deleteInSwitch: false, trigger: 'server_teardown' });deleted.push(row.id);} catch (error) {failed.push({ agentId: row.id, error: String(error) });diff --git a/console/apps/switch-console-desktop/src/main/core/switch-servers/servers-store.db.test.ts b/console/apps/switch-console-desktop/src/main/core/switch-servers/servers-store.db.test.tsindex 56353cbb8..2102d693d 100644--- a/console/apps/switch-console-desktop/src/main/core/switch-servers/servers-store.db.test.ts+++ b/console/apps/switch-console-desktop/src/main/core/switch-servers/servers-store.db.test.ts@@ -129,6 +129,7 @@ describe('servers-store: rename & delete', () => {expect(telemetryMocks.trackEvent).toHaveBeenCalledTimes(1);expect(telemetryMocks.trackEvent).toHaveBeenCalledWith('server_added', {server_kind: 'local',+ outcome: 'success',});});@@ -145,6 +146,7 @@ describe('servers-store: rename & delete', () => {expect(telemetryMocks.trackEvent).toHaveBeenCalledTimes(1);expect(telemetryMocks.trackEvent).toHaveBeenCalledWith('server_added', {server_kind: 'remote_managed',+ outcome: 'success',});});@@ -168,21 +170,60 @@ describe('servers-store: rename & delete', () => {});describe('addServer telemetry', () => {- it('reports an externally-hosted server', async () => {+ it('leaves an externally-hosted server for its one caller to report', async () => {+ // The controller owns both outcomes of that add, so that one press of Add+ // cannot produce a success here and a failure there.await addServer({name: 'External server',gatewayUrl: 'https://gw.example.com',apiUrl: 'https://api.example.com',});- expect(telemetryMocks.trackEvent).toHaveBeenCalledTimes(1);- expect(telemetryMocks.trackEvent).toHaveBeenCalledWith('server_added', {- server_kind: 'external',- });+ expect(telemetryMocks.trackEvent).not.toHaveBeenCalled();});});describe('removeServer', () => {+ it('reports the kind of server that was removed', async () => {+ await fixture.db.insert(switchServers).values({+ id: 'srv-ext',+ name: 'External',+ gatewayUrl: 'https://gw.example.com',+ apiUrl: 'https://api.example.com',+ });++ await removeServer('srv-ext');++ expect(telemetryMocks.trackEvent).toHaveBeenCalledWith('server_removed', {+ server_kind: 'external',+ });+ });++ it('reports a managed server by the kind it was managed as', async () => {+ await fixture.db.insert(switchServers).values({+ id: 'srv-rm',+ name: 'Remote',+ gatewayUrl: 'https://gw2.example.com',+ apiUrl: 'https://api2.example.com',+ managed: true,+ managementKind: 'remote',+ sshHost: 'build-box',+ });++ await removeServer('srv-rm');++ expect(telemetryMocks.trackEvent).toHaveBeenCalledWith('server_removed', {+ server_kind: 'remote_managed',+ });+ });++ it('reports nothing for a server that was already gone', async () => {+ // A no-op remove is not a server being removed.+ await removeServer('srv-missing');++ expect(telemetryMocks.trackEvent).not.toHaveBeenCalled();+ });+it('unlinks the server’s agents (keeps them), deletes the row, and clears the active pointer', async () => {await fixture.db.insert(locations)diff --git a/console/apps/switch-console-desktop/src/main/core/switch-servers/servers-store.ts b/console/apps/switch-console-desktop/src/main/core/switch-servers/servers-store.tsindex e50c6a470..9c027fa26 100644--- a/console/apps/switch-console-desktop/src/main/core/switch-servers/servers-store.ts+++ b/console/apps/switch-console-desktop/src/main/core/switch-servers/servers-store.ts@@ -1,6 +1,7 @@import { randomUUID } from 'node:crypto';import { and, desc, eq, isNull, ne, or, sql } from 'drizzle-orm';import { encryptedAppSecretsStore } from '@main/core/secrets/encrypted-app-secrets-store';+import type { TelemetryEventMap } from '@main/core/telemetry/events';import { trackEvent } from '@main/core/telemetry/telemetry-service';import { db } from '@main/db/client';import { agents, kv, type SwitchServerRow, switchServers } from '@main/db/schema';@@ -160,6 +161,7 @@ export async function ensureManagedServer(// already exists, and that is not a server being added.trackEvent('server_added', {server_kind: ref.kind === 'remote' ? 'remote_managed' : 'local',+ outcome: 'success',});return mapRow(row);}@@ -184,7 +186,11 @@ export async function addServer(params: AddServerParams): Promise<SwitchServer>updatedAt: sql`CURRENT_TIMESTAMP`,}).returning();- trackEvent('server_added', { server_kind: 'external' });+ // Not reported here, unlike the managed insert above: registering a URL is a+ // discrete action with one caller, so the controller reports both of its+ // outcomes together and a single Add cannot produce two events. The managed+ // kinds have no such single owner — two services call that path and so does+ // every restart — which is why it is reported at the insert instead.return mapRow(row);}@@ -218,6 +224,10 @@ export async function renameServer(params: RenameServerParams): Promise<SwitchSe}export async function removeServer(id: string): Promise<void> {+ // Read before the row goes, since nothing afterwards can say what kind it was+ // — but a read that exists only to describe the removal must not prevent it.+ const server = await getServer(id).catch(() => null);+await deleteSessionCookie(id);// Unlink agents explicitly: SQLite's ALTER TABLE ADD COLUMN can't carry an// ON DELETE clause, so the FK's set-null isn't enforced by the engine.@@ -226,6 +236,17 @@ export async function removeServer(id: string): Promise<void> {if ((await getActiveServerId()) === id) {await db.delete(kv).where(eq(kv.key, ACTIVE_SERVER_KV_KEY));}++ // Removing an already-absent server is not a server being removed.+ if (server) trackEvent('server_removed', { server_kind: serverKindOf(server) });+}++/** The reported kind of a server, in the same terms `server_added` uses. */+export function serverKindOf(+ server: SwitchServer+): TelemetryEventMap['server_added']['server_kind'] {+ if (!server.managed) return 'external';+ return server.managementKind === 'remote' ? 'remote_managed' : 'local';}export async function getActiveServerId(): Promise<string | null> {diff --git a/console/apps/switch-console-desktop/src/main/core/switch-setup/remote-switch-setup.ts b/console/apps/switch-console-desktop/src/main/core/switch-setup/remote-switch-setup.tsindex c0eadf970..8c1d2da1f 100644--- a/console/apps/switch-console-desktop/src/main/core/switch-setup/remote-switch-setup.ts+++ b/console/apps/switch-console-desktop/src/main/core/switch-setup/remote-switch-setup.ts@@ -5,6 +5,7 @@ import { createRemoteHomePluginFs } from '@main/core/agent-runtime/impl/remote-himport { SshExecutionContext } from '@main/core/execution-context/ssh-execution-context';import { sshConnectionIdForHost } from '@main/core/locations/location-transport';import { ensureSshConnected } from '@main/core/ssh/connect/connect-agent-ssh';+import { agentTypeOf } from '@main/core/telemetry/agent-type';import { trackEvent } from '@main/core/telemetry/telemetry-service';import { log } from '@main/lib/logger';import { isNewerVersion } from '@main/lib/semver';@@ -425,29 +426,57 @@ export class RemoteSwitchSetupService {* would otherwise fail it after the uninstall has already succeeded.*/async update(agentId: string): Promise<SwitchSetupResult> {+ if (getPlugin(agentId).capabilities.switchSetup.kind === 'none') {+ return { success: false, message: 'Switch setup is not supported for this agent.' };+ }+ const { result, wasReinstall } = await this.runUpdate(agentId);+ trackEvent('connector_updated', {+ agent_type: agentTypeOf(agentId),+ target: 'remote',+ outcome: result.success ? 'success' : 'failure',+ was_reinstall: wasReinstall,+ });+ return result;+ }++ private async runUpdate(+ agentId: string+ ): Promise<{ result: SwitchSetupResult; wasReinstall: boolean }> {// Installing overwrites in place, so update is the same operation — there// is no removed-but-not-reinstalled window to report on.if (getPlugin(agentId).capabilities.switchSetup.kind === 'files') {const version = connectorVersion(agentId);- return this.runFiles(agentId, (files, fs) => files.install(fs, { version }));+ const result = await this.runFiles(agentId, (files, fs) => files.install(fs, { version }));+ return { result, wasReinstall: false };}const resolved = await this.resolve(agentId);- if (!resolved)- return { success: false, message: 'Switch setup is not supported for this agent.' };+ if (!resolved) {+ return {+ result: { success: false, message: 'Switch setup is not supported for this agent.' },+ wasReinstall: false,+ };+ }const { descriptor, bin, ref, marketplaceSource, rules } = resolved;try {await this.ensureMarketplace(bin, descriptor.marketplaceName, marketplaceSource, rules);} catch (err) {- return { success: false, message: `Could not add marketplace: ${String(err)}` };+ return {+ result: { success: false, message: `Could not add marketplace: ${String(err)}` },+ wasReinstall: false,+ };}const updateArgs = rules.updateArgs(ref, descriptor.scope);if (updateArgs) {const res = await this.run(bin, updateArgs);- return res.code === 0- ? { success: true }- : { success: false, message: res.stderr.trim() || 'Update failed.' };+ return {+ result:+ res.code === 0+ ? { success: true }+ : { success: false, message: res.stderr.trim() || 'Update failed.' },+ wasReinstall: false,+ };}// No per-plugin update verb (Codex): remove then re-add. A failed re-add@@ -455,19 +484,26 @@ export class RemoteSwitchSetupService {const removed = await this.run(bin, rules.uninstallArgs(ref, descriptor.scope));if (removed.code !== 0) {return {- success: false,- message: removed.stderr.trim() || 'Update failed: could not remove the installed plugin.',+ result: {+ success: false,+ message: removed.stderr.trim() || 'Update failed: could not remove the installed plugin.',+ },+ wasReinstall: true,};}const added = await this.run(bin, rules.installArgs(ref, descriptor.scope));- return added.code === 0- ? { success: true }- : {- success: false,- message:- added.stderr.trim() ||- 'Update failed: the plugin was removed but could not be reinstalled. Install it again for this host.',- };+ return {+ result:+ added.code === 0+ ? { success: true }+ : {+ success: false,+ message:+ added.stderr.trim() ||+ 'Update failed: the plugin was removed but could not be reinstalled. Install it again for this host.',+ },+ wasReinstall: true,+ };}/** Status of every Switch-supported agent type's connector plugin on this host. */diff --git a/console/apps/switch-console-desktop/src/main/core/switch-setup/switch-setup-service.ts b/console/apps/switch-console-desktop/src/main/core/switch-setup/switch-setup-service.tsindex f074a207f..0424650ee 100644--- a/console/apps/switch-console-desktop/src/main/core/switch-setup/switch-setup-service.ts+++ b/console/apps/switch-console-desktop/src/main/core/switch-setup/switch-setup-service.ts@@ -5,6 +5,7 @@ import type { ISwitchSetupFilesBehavior, PluginFs } from '@switch-console/core/aimport { resolveCommandPath } from '@switch-console/core/deps/runtime';import { type ArtifactName, artifactVersion } from '@switch-console/shared';import { LocalExecutionContext } from '@main/core/execution-context/local-execution-context';+import { agentTypeOf } from '@main/core/telemetry/agent-type';import { trackEvent } from '@main/core/telemetry/telemetry-service';import { log } from '@main/lib/logger';import { isNewerVersion } from '@main/lib/semver';@@ -456,15 +457,52 @@ class SwitchSetupService {* resolves against whatever marketplace is registered, so a stale source would* otherwise fail it — after the uninstall has already succeeded.*/+ /**+ * Update the connector, reporting the outcome.+ *+ * The "not supported" answer is not an attempt and is not reported — the same+ * distinction `install` draws with its `attempted` flag, without which every+ * agent that has no connector would look like a failing update.+ */async update(agentId: string): Promise<SwitchSetupResult> {+ if (getPlugin(agentId).capabilities.switchSetup.kind === 'none') {+ return { success: false, message: 'Switch setup is not supported for this agent.' };+ }+ const { result, wasReinstall } = await this.runUpdate(agentId);+ trackEvent('connector_updated', {+ agent_type: agentTypeOf(agentId),+ target: 'local',+ outcome: result.success ? 'success' : 'failure',+ was_reinstall: wasReinstall,+ });+ return result;+ }++ /**+ * The update itself. `wasReinstall` says whether the host had a single update+ * verb or the connector had to be removed and put back — Codex has no update+ * verb, so for it every update is the second kind, with a window in between+ * where nothing is installed.+ */+ private async runUpdate(+ agentId: string+ ): Promise<{ result: SwitchSetupResult; wasReinstall: boolean }> {// Installing a file-based connector overwrites in place, so update is the// same operation — there is no removed-but-not-reinstalled window.if (getPlugin(agentId).capabilities.switchSetup.kind === 'files') {- return this.runFiles(agentId, (files, fs, version) => files.install(fs, { version }));+ const result = await this.runFiles(agentId, (files, fs, version) =>+ files.install(fs, { version })+ );+ // Overwritten in place: neither a verb update nor a remove-and-replace.+ return { result, wasReinstall: false };}const resolved = await this.resolve(agentId);- if (!resolved)- return { success: false, message: 'Switch setup is not supported for this agent.' };+ if (!resolved) {+ return {+ result: { success: false, message: 'Switch setup is not supported for this agent.' },+ wasReinstall: false,+ };+ }const { descriptor, bin, ref, rules } = resolved;try {@@ -475,36 +513,63 @@ class SwitchSetupService {rules);} catch (err) {- return { success: false, message: `Could not add marketplace: ${String(err)}` };+ return {+ result: { success: false, message: `Could not add marketplace: ${String(err)}` },+ wasReinstall: false,+ };}const updateArgs = rules.updateArgs(ref, descriptor.scope);if (updateArgs) {const res = await this.run(bin, updateArgs);- return res.code === 0- ? { success: true }- : { success: false, message: res.stderr.trim() || 'Update failed.' };+ return {+ result:+ res.code === 0+ ? { success: true }+ : { success: false, message: res.stderr.trim() || 'Update failed.' },+ wasReinstall: false,+ };}const removed = await this.run(bin, rules.uninstallArgs(ref, descriptor.scope));if (removed.code !== 0) {return {- success: false,- message: removed.stderr.trim() || 'Update failed: could not remove the installed plugin.',+ result: {+ success: false,+ message: removed.stderr.trim() || 'Update failed: could not remove the installed plugin.',+ },+ wasReinstall: true,};}const added = await this.run(bin, rules.installArgs(ref, descriptor.scope));- return added.code === 0- ? { success: true }- : {- success: false,- message:- added.stderr.trim() ||- 'Update failed: the plugin was removed but could not be reinstalled. Install it again from Settings → Agents.',- };+ return {+ result:+ added.code === 0+ ? { success: true }+ : {+ success: false,+ message:+ added.stderr.trim() ||+ 'Update failed: the plugin was removed but could not be reinstalled. Install it again from Settings → Agents.',+ },+ wasReinstall: true,+ };}async uninstall(agentId: string): Promise<SwitchSetupResult> {+ if (getPlugin(agentId).capabilities.switchSetup.kind === 'none') {+ return { success: false, message: 'Switch setup is not supported for this agent.' };+ }+ const result = await this.runUninstall(agentId);+ trackEvent('connector_uninstalled', {+ agent_type: agentTypeOf(agentId),+ target: 'local',+ outcome: result.success ? 'success' : 'failure',+ });+ return result;+ }++ private async runUninstall(agentId: string): Promise<SwitchSetupResult> {if (getPlugin(agentId).capabilities.switchSetup.kind === 'files') {return this.runFiles(agentId, (files, fs) => files.uninstall(fs));}diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/agent-type.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/agent-type.tsnew file mode 100644index 000000000..4a4df4f2f--- /dev/null+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/agent-type.ts@@ -0,0 +1,19 @@+import {+ isValidProviderId,+ type AgentProviderId,+} from '@shared/core/providers/agent-provider-registry';++/**+ * A provider id, checked rather than trusted.+ *+ * The column it comes from is typed but not constrained, and some callers pass a+ * dependency id that may name no agent at all — so an unrecognised value is+ * reported as unrecognised and never passed through as free text.+ *+ * Kept apart from the location helper deliberately: this is a pure function, and+ * living beside one that reads the database made every caller import the+ * database with it.+ */+export function agentTypeOf(providerId: string): AgentProviderId | 'unknown' {+ return isValidProviderId(providerId) ? providerId : 'unknown';+}diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/bridge-platform.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/bridge-platform.tsnew file mode 100644index 000000000..ad3198e09--- /dev/null+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/bridge-platform.ts@@ -0,0 +1,25 @@+import type { TelemetryBridgePlatform } from './events';++/**+ * The messaging platforms this app knows the names of.+ *+ * The server decides what bridge types exist and names them as free text, so+ * there is no union to import — the list is fetched at runtime and could contain+ * anything. This is the same treatment provider ids get: an unrecognised value+ * is reported as unrecognised rather than passed through, because a platform key+ * we have never heard of is still a string arriving from outside this app.+ */+const KNOWN_PLATFORMS = new Set(['slack', 'mattermost', 'discord', 'teams', 'telegram']);++/**+ * Narrow a bridge type to something reportable.+ *+ * `other` means the server named a platform we do not have a value for — worth+ * knowing, and distinct from `unknown`, which means we could not find out at+ * all. Collapsing the two would make a new platform look like a lookup failure.+ */+export function bridgePlatformOfType(type: string | null | undefined): TelemetryBridgePlatform {+ if (type === null || type === undefined || type === '') return 'unknown';+ const normalised = type.trim().toLowerCase();+ return KNOWN_PLATFORMS.has(normalised) ? (normalised as TelemetryBridgePlatform) : 'other';+}diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/catalogue.test.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/catalogue.test.tsnew file mode 100644index 000000000..43656fd71--- /dev/null+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/catalogue.test.ts@@ -0,0 +1,148 @@+import { describe, expect, it } from 'vitest';+import { TELEMETRY_EVENT_PROPERTIES, type TelemetryEventName } from './events';+import { buildOtlpPayload, type TelemetryContext } from './relay-client';++/**+ * Every catalogued event can actually be sent.+ *+ * The type map and the runtime allow-list are two lists that have to agree, and+ * nothing else checks that they do at the level that matters: a property named+ * in one and absent from the other only fails when a real user performs that+ * action, at which point the event is dropped and a line appears in a log+ * nobody is reading. This walks the whole catalogue instead.+ *+ * It is deliberately mechanical. It cannot tell you an event fires at the right+ * moment — only that if it fires, it can be built and carries nothing but what+ * it declared. Nor can it see the type map: `TelemetryEventMap` is erased by the+ * time this runs, and the samples below are derived from the allow-list, so a+ * property declared in one and missing from the other is invisible from here.+ * `_everyPropertyIsAllowListed` in `./events` is what catches that, at compile+ * time.+ */++const CONTEXT: TelemetryContext = {+ clientId: '11111111-2222-4333-8444-555555555555',+ appVersion: '1.2.3',+ osType: 'darwin',+ osVersion: '24.3.0',+ build: 'stable',+ timeMs: 1_700_000_000_000,+};++/**+ * A value of the right kind for each property, chosen by name.+ *+ * Counts are numbers, the yes/no properties are booleans, and everything else+ * is a placeholder string — the builder does not check a string against the+ * catalogue's unions, so any string exercises the same path.+ */+function sampleFor(property: string): string | number | boolean {+ if (property.endsWith('_count')) return 3;+ if (+ property.startsWith('has_') ||+ property.startsWith('was_') ||+ property.startsWith('picked_') ||+ property === 'connected_to_room' ||+ property === 'delete_in_switch' ||+ property === 'resolved' ||+ property === 'cold_start'+ ) {+ return true;+ }+ return 'sample';+}++const EVENT_NAMES = Object.keys(TELEMETRY_EVENT_PROPERTIES) as TelemetryEventName[];++function sampleEvent(name: TelemetryEventName): Record<string, string | number | boolean> {+ return Object.fromEntries(TELEMETRY_EVENT_PROPERTIES[name].map((p) => [p, sampleFor(p)]));+}++type LogRecord = {+ eventName: string;+ attributes: { key: string; value: { stringValue?: string } }[];+};++/** The one log record a payload carries. */+function recordOf(payload: Record<string, unknown>): LogRecord {+ const resourceLogs = payload.resourceLogs as [{ scopeLogs: [{ logRecords: [LogRecord] }] }];+ return resourceLogs[0].scopeLogs[0].logRecords[0];+}++describe('the catalogue as a whole', () => {+ it('has at least the events this work was meant to add', () => {+ // A floor, not an assertion about the exact number: the point is that the+ // catalogue did not silently shrink.+ expect(EVENT_NAMES.length).toBeGreaterThanOrEqual(35);+ });++ it.each(EVENT_NAMES)('builds a payload for %s', (name) => {+ const payload = buildOtlpPayload(name, sampleEvent(name) as never, CONTEXT);++ expect(JSON.stringify(payload)).toContain(`switch_console.${name}`);+ });++ it.each(EVENT_NAMES)('sends nothing beyond what %s declares', (name) => {+ const smuggled = {+ ...sampleEvent(name),+ working_dir: '/Users/someone/secret-project',+ error_message: 'ENOENT: no such file',+ room_name: 'incident-response',+ };++ const payload = buildOtlpPayload(name, smuggled as never, CONTEXT);+ const wire = JSON.stringify(payload);++ expect(wire).not.toContain('secret-project');+ expect(wire).not.toContain('ENOENT');+ expect(wire).not.toContain('incident-response');+ // The three above are the kinds of thing that must never leak, anywhere in+ // the payload. This is the check that generalises: the record carries the+ // event's own properties, the name it is filed under and the build that sent+ // it, and a search for words a test happened to think of would pass whatever+ // else arrived alongside them.+ const carried = recordOf(payload).attributes.map((a) => a.key);+ expect(carried.sort()).toEqual(+ [...TELEMETRY_EVENT_PROPERTIES[name], 'build', 'event.name'].sort()+ );+ });++ it.each(EVENT_NAMES)('refuses to send %s with a property missing', (name) => {+ const properties = sampleEvent(name);+ const declared = TELEMETRY_EVENT_PROPERTIES[name];+ if (declared.length === 0) return;++ delete properties[declared[0]];++ expect(() => buildOtlpPayload(name, properties as never, CONTEXT)).toThrow(+ /missing the catalogued property/+ );+ });++ it('names every event under this product, in both the places the relay looks', () => {+ // One project holds every product's events, so the prefix is what says whose+ // this is. And the name goes in both the record's own field and an attribute:+ // the exporter reads the first, the relay's "records with no name" filter+ // tests the second, and a record carrying only one of them is dropped+ // somewhere along a path where every step answers 200.+ for (const name of EVENT_NAMES) {+ const record = recordOf(buildOtlpPayload(name, sampleEvent(name) as never, CONTEXT));+ const named = `switch_console.${name}`;++ expect(record.eventName).toBe(named);+ expect(record.attributes.find((a) => a.key === 'event.name')?.value.stringValue).toBe(named);+ }+ });++ it('uses snake_case for every event name and every property', () => {+ // The catalogue's own convention, and the one thing a dashboard cannot+ // paper over once half the events break it.+ const snake = /^[a-z][a-z0-9_]*$/;+ for (const name of EVENT_NAMES) {+ expect(name).toMatch(snake);+ for (const property of TELEMETRY_EVENT_PROPERTIES[name]) {+ expect(property).toMatch(snake);+ }+ }+ });+});diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/cli-failure.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/cli-failure.tsnew file mode 100644index 000000000..ed61c6dc5--- /dev/null+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/cli-failure.ts@@ -0,0 +1,38 @@+import type { TelemetryCliFailure } from './events';++/**+ * The codes the three dependency operations return.+ *+ * Install, update and uninstall each have their own error union, and they+ * overlap without being identical — a shared set of command failures at the+ * centre, and their own ends. Rather than three near-duplicate telemetry unions,+ * this maps every discriminant any of them can produce onto one, and refuses to+ * guess at anything else.+ *+ * A code that arrives here unrecognised becomes `error` rather than being passed+ * through: these are read off a `Result` whose type says what they can be, but+ * the value crossed a package boundary and a new variant added upstream must not+ * become free text in a payload.+ */+const CLI_FAILURE_CODES: Record<string, TelemetryCliFailure> = {+ 'unknown-dependency': 'unknown_dependency',+ 'no-install-command': 'no_install_command',+ 'no-update-strategy': 'no_update_strategy',+ 'no-uninstall-strategy': 'no_uninstall_strategy',+ 'no-uninstall-command': 'no_uninstall_command',+ 'permission-denied': 'permission_denied',+ 'command-failed': 'command_failed',+ 'pty-open-failed': 'pty_open_failed',+ 'not-detected-after-install': 'not_detected_after_install',+ 'not-detected-after-update': 'not_detected_after_update',+ 'still-present': 'still_present',+};++export function cliFailureReason(result: {+ success: boolean;+ error?: { type?: string };+}): TelemetryCliFailure {+ if (result.success) return 'none';+ const type = result.error?.type;+ return (type && CLI_FAILURE_CODES[type]) || 'error';+}diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/controller.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/controller.tsnew file mode 100644index 000000000..313b5cbcb--- /dev/null+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/controller.ts@@ -0,0 +1,21 @@+import { createRPCController } from '@shared/lib/ipc/rpc';+import { trackFromRenderer, type RendererTelemetryRequest } from './renderer-events';++/**+ * The interface's one way to report something.+ *+ * Deliberately a single procedure taking a name and a bag of properties, rather+ * than one procedure per event: what may be reported is decided by the list in+ * `./renderer-events`, in the main process, and a shape that made each event its+ * own entry point would spread that decision across the surface it is meant to+ * constrain.+ *+ * It returns nothing and cannot fail from the caller's point of view — reporting+ * must never change what the app does, and a rejected request is a bug to fix in+ * the app rather than a condition for a screen to handle.+ */+export const telemetryController = createRPCController({+ track: async (request: RendererTelemetryRequest): Promise<void> => {+ trackFromRenderer(request);+ },+});diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/events.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/events.tsindex a326f9e3d..b87e8f86e 100644--- a/console/apps/switch-console-desktop/src/main/core/telemetry/events.ts+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/events.ts@@ -1,4 +1,14 @@+import type { InstallMethod } from '@switch-console/core/deps';import type { AgentProviderId } from '@shared/core/providers/agent-provider-registry';+import type { HostSetupStepKind } from '@shared/core/remote-hosts/setup';+import type { SearchStatus } from '@shared/core/search';+import type { AppSettingsKeyName } from '@shared/core/settings/setting-keys';+import type { RendererTelemetryEvents } from '@shared/core/telemetry/renderer-events';+import type {+ SessionProvisionTrigger,+ SessionStartSource,+ UiEntryPoint,+} from '@shared/core/telemetry/reporting';/*** Where the thing being reported ran: this machine, or an SSH host.@@ -18,13 +28,232 @@ export type TelemetryLocationKind = 'local' | 'remote' | 'unknown';*/export type TelemetryAgentType = AgentProviderId | 'unknown';+/**+ * Whether the action the event reports completed or failed.+ *+ * Every event that reports an action a user asked for carries this, because an+ * event emitted only on success makes the entire failure population invisible —+ * and a rate nobody can see is worse than no rate at all.+ */+export type TelemetryOutcome = 'success' | 'failure';++/**+ * Why an action failed, as an enumerated code.+ *+ * `none` rather than an absent property on success: every event of a given name+ * then carries the same keys, so a missing value in the data means a send that+ * went wrong rather than an outcome nobody thought about. The variants are the+ * `kind`/`type` discriminants of the failure unions these paths already return,+ * transliterated to snake_case — never a message.+ */+export type TelemetryAgentCreateFailure =+ | 'none'+ | 'unauthenticated'+ | 'name_conflict'+ | 'credentials_conflict'+ | 'invalid_name'+ /**+ * The two the other way into this — dropping a folder on the sidebar — hits+ * most: the directory holds no agent configuration, or it holds one belonging+ * to an identity this server has never heard of. Both are a person pointing+ * the app at the wrong folder, which is worth telling apart from a fault.+ */+ | 'not_configured'+ | 'agent_not_on_server'+ | 'error';++export type TelemetrySessionStartFailure =+ | 'none'+ | 'agent_not_found'+ | 'already_exists'+ | 'spawn_failed';++/**+ * Why removing an agent failed.+ *+ * The path signals failure by throwing rather than by returning a union, so the+ * codes come from the errors' own types: `GatewayError.kind` for the three+ * gateway cases, and a dedicated class for an agent with no identity to delete.+ * `error` is the honest bucket for everything not separated out; widening it+ * means naming a new case, never passing a message through.+ */+export type TelemetryAgentRemoveFailure =+ | 'none'+ | 'not_linked_to_switch'+ | 'gateway_unauthorized'+ | 'gateway_http'+ | 'gateway_network'+ | 'error';++/** Why resetting a remote agent failed. Also named rather than derived. */+export type TelemetryAgentResetFailure =+ | 'none'+ | 'agent_not_found'+ | 'not_remote'+ | 'connect'+ | 'error';++/**+ * What removed an agent.+ *+ * Wiping a managed server deletes every agent on it, through the same function+ * a person uses to delete one. Without this, one click on Reset looks+ * identical to a dozen people giving up on their agents.+ */+export type TelemetryAgentRemoveTrigger = 'user' | 'server_teardown';++/** Installing, updating or removing an agent's own CLI. */+export type TelemetryCliAction = 'install' | 'update' | 'uninstall';++/**+ * How a CLI was installed. The installer capability's own closed set, plus+ * `unspecified` for the callers that do not name one — the parameter is optional+ * on every one of these paths.+ */+export type TelemetryInstallMethod = InstallMethod | 'unspecified';++/**+ * Why installing, updating or removing a CLI failed.+ *+ * The union of the three operations' own error types, which share most of their+ * cases and differ at the ends. `error` covers a throw, which these paths are+ * not supposed to do but can.+ */+export type TelemetryCliFailure =+ | 'none'+ | 'unknown_dependency'+ | 'no_install_command'+ | 'no_update_strategy'+ | 'no_uninstall_strategy'+ | 'no_uninstall_command'+ | 'permission_denied'+ | 'command_failed'+ | 'pty_open_failed'+ | 'not_detected_after_install'+ | 'not_detected_after_update'+ | 'still_present'+ | 'error';++/**+ * Which messaging platform a room or bridge is on.+ *+ * The server names the platform as free text, so this is narrowed at the emitter+ * rather than trusted — the same treatment provider ids get. `other` is a+ * platform we do not know about, `unknown` is one we could not read.+ */+export type TelemetryBridgePlatform =+ | 'slack'+ | 'mattermost'+ | 'discord'+ | 'teams'+ | 'telegram'+ | 'other'+ | 'unknown';++/**+ * What asked for an update check.+ *+ * `startup` and `scheduled` are the app's own; `user` is a menu item or a button+ * somebody pressed. Note a manual check that lands while an automatic one is+ * already running joins it rather than starting a new one, so a small number of+ * user checks are reported under the trigger that got there first.+ */+export type TelemetryUpdateTrigger = 'user' | 'startup' | 'scheduled';++export type TelemetryBridgeFailure = 'none' | 'unauthenticated' | 'forbidden' | 'invalid' | 'error';++export type TelemetryRoomCreateFailure =+ | 'none'+ | 'unauthenticated'+ | 'bridge_unavailable'+ | 'invalid'+ | 'unreachable'+ | 'error';++/** How someone signed in. Not a setting — which of the two forms they used. */+export type TelemetryAuthMethod = 'password' | 'oidc';++/**+ * Why a sign-in failed. `cancelled` is the browser window being closed on the+ * single-sign-on path, which is someone changing their mind rather than a fault.+ */+export type TelemetrySignInFailure =+ | 'none'+ | 'invalid_credentials'+ | 'cancelled'+ | 'failed'+ | 'unreachable';++/** What was done to a step of a remote host's setup. */+export type TelemetryHostSetupAction = 'install' | 'update' | 'skip';++export type TelemetryManagedServerAction = 'start' | 'stop' | 'reset';++export type TelemetryManagedServerFailure =+ | 'none'+ | 'docker_not_installed'+ | 'docker_daemon_down'+ | 'version_downgrade'+ | 'error';++/**+ * Whether Docker was usable.+ *+ * `unknown` is honest rather than lazy: only starting a stack probes for Docker,+ * so stopping or resetting one genuinely does not know, and answering `available`+ * there would be a guess indistinguishable from a reading.+ */+export type TelemetryDockerAvailability = 'available' | 'unavailable' | 'unknown';++/**+ * Which way round agents and rooms were joined.+ *+ * The same operation serves both screens, and one of them loops it once per+ * room — so without this, adding one agent to five rooms is indistinguishable+ * from five separate one-agent adds.+ */+export type TelemetryRoomAgentsDirection = 'agents_to_room' | 'room_to_agents';++/**+ * Which control the user reached the action from, and who started a session.+ *+ * Both are declared in `@shared` because the renderer names them and the main+ * process reports them; see that module for what the variants mean.+ */+export type TelemetryEntryPoint = UiEntryPoint;+export type TelemetrySessionStartSource = SessionStartSource;++/** A retry's trigger, minus `initial`, which is not a retry and is not sent. */+export type TelemetrySessionProvisionTrigger = Exclude<SessionProvisionTrigger, 'initial'>;++/** Which setting was changed. The keys of the app's settings, and nothing else. */+export type TelemetrySettingKey = AppSettingsKeyName;++/** How a search ended. The search's own union, reused rather than restated. */+export type TelemetrySearchStatus = SearchStatus;++/** The kinds of server this install can hold. Named once, used by five events. */+export type TelemetryServerKind = 'local' | 'remote_managed' | 'external';++/**+ * A setup step's kind, reused from the remote-host model rather than restated.+ *+ * `unknown` is this catalogue's own addition, not the model's: a step in a plan+ * always has a real kind, but a run that fails before it can build the plan has+ * no step to read one from. Reporting such a failure under a real kind would+ * add it to that kind's tally, and "which step do people get stuck on" is the+ * one question this event exists to answer.+ */+export type TelemetryHostSetupStepKind = HostSetupStepKind | 'unknown';+/*** Every event the app may send, and everything each one may carry.*- * The property types are the enforcement, not documentation: literal unions and- * numbers only, so a caller cannot reach a payload with a path, a name, an- * error message or anything else free-text. Adding a `string` here removes that- * guarantee for the whole catalogue — add a union of the values you mean.+ * The property types are the enforcement, not documentation: literal unions,+ * numbers and booleans only, so a caller cannot reach a payload with a path, a+ * name, an error message or anything else free-text. Adding a `string` here+ * removes that guarantee for the whole catalogue — add a union of the values you+ * mean.** The ambient fields every event carries — app version, operating system, build* channel, install id — are added by the emitter and are not repeated here.@@ -47,10 +276,21 @@ export type TelemetryEventMap = {agent_created: {agent_type: TelemetryAgentType;location: TelemetryLocationKind;+ outcome: TelemetryOutcome;+ failure_reason: TelemetryAgentCreateFailure;+ entry_point: TelemetryEntryPoint;};session_started: {agent_type: TelemetryAgentType;location: TelemetryLocationKind;+ outcome: TelemetryOutcome;+ failure_reason: TelemetrySessionStartFailure;+ entry_point: TelemetryEntryPoint;+ start_source: TelemetrySessionStartSource;+ /** Whether the session was given something to do at launch. Never the text. */+ has_initial_prompt: boolean;+ /** Whether a Switch room was chosen before the session was created. */+ connected_to_room: boolean;};/*** A session finished. `normal` is a session the user ended (deleted or@@ -62,15 +302,279 @@ export type TelemetryEventMap = {location: TelemetryLocationKind;outcome: 'normal' | 'failed';};+ /**+ * A server was added to this install.+ *+ * `outcome: 'failure'` is reported only for `external` — registering a URL is+ * the one add that is a discrete action able to fail on its own. Bringing up a+ * managed stack fails in ways of its own (no Docker, a version downgrade),+ * which `managed_server_action` reports with the dimension that explains them;+ * counting those here as well would double-count the same wall.+ */server_added: {/** `external` is a server the user registered by URL: Switch Console does not run it. */server_kind: 'local' | 'remote_managed' | 'external';+ outcome: TelemetryOutcome;};connector_installed: {agent_type: TelemetryAgentType;target: TelemetryLocationKind;outcome: 'success' | 'failure';};+ /**+ * The app checked for an update. `trigger` separates a check someone asked for+ * from the hourly one, because only the first says anything about intent.+ */+ update_checked: {+ trigger: TelemetryUpdateTrigger;+ result: 'available' | 'up_to_date' | 'failed';+ };+ update_downloaded: {+ outcome: TelemetryOutcome;+ };+ /**+ * An install was started — not finished.+ *+ * Deliberately named for what it can actually observe. A successful install+ * quits the app, so there is no moment afterwards in which to report one; what+ * this counts is the point the update was handed to the installer. Whether it+ * worked is answered by the next `app_launched` and its version.+ */+ update_install_started: {+ outcome: TelemetryOutcome;+ };+ /** A messaging platform was connected to a server. */+ bridge_connected: {+ bridge_platform: TelemetryBridgePlatform;+ outcome: TelemetryOutcome;+ failure_reason: TelemetryBridgeFailure;+ };+ /**+ * A messaging platform was disconnected from a server.+ *+ * Carries an outcome because the gateway refuses this one routinely — it is+ * admin-only, and a non-admin's attempt returns rather than throws. Without it+ * a refusal is indistinguishable from a disconnection that happened.+ */+ bridge_disconnected: {+ bridge_platform: TelemetryBridgePlatform;+ outcome: TelemetryOutcome;+ };+ /** Someone linked their account on a messaging platform to their Switch user. */+ bridge_identity_claimed: {+ bridge_platform: TelemetryBridgePlatform;+ outcome: TelemetryOutcome;+ };+ /**+ * The connector was updated. `was_reinstall` separates a host with a single+ * update verb from one where the connector must be removed and put back —+ * Codex has no update verb, so for it every update has a window in the middle+ * with nothing installed, and a failure there leaves the agent without one.+ */+ connector_updated: {+ agent_type: TelemetryAgentType;+ target: 'local' | 'remote';+ outcome: TelemetryOutcome;+ was_reinstall: boolean;+ };+ /**+ * The connector was removed. The churn signal.+ *+ * Only ever `local`: there is no remote uninstall anywhere above the service,+ * so a `remote` value here would be one that cannot occur.+ */+ connector_uninstalled: {+ agent_type: TelemetryAgentType;+ target: 'local';+ outcome: TelemetryOutcome;+ };+ /**+ * An agent was removed. `delete_in_switch` says whether its identity on the+ * server went with it, which is the difference between leaving the app and+ * leaving the organisation.+ */+ agent_removed: {+ agent_type: TelemetryAgentType;+ location: TelemetryLocationKind;+ delete_in_switch: boolean;+ trigger: TelemetryAgentRemoveTrigger;+ outcome: TelemetryOutcome;+ failure_reason: TelemetryAgentRemoveFailure;+ };+ /**+ * A remote agent was reset — every one of its panes on the host killed and the+ * agent brought back up. Remote-only, and a real SSH operation, so unlike most+ * of this catalogue it fails for reasons outside the app.+ */+ agent_reset: {+ agent_type: TelemetryAgentType;+ outcome: TelemetryOutcome;+ failure_reason: TelemetryAgentResetFailure;+ };+ /**+ * A server was removed from this install.+ *+ * It carries no count of agents removed with it, because removing a server+ * removes none: it unlinks them. The deletion that does remove them is a+ * separate operation the UI runs first, and nothing on this side sees both —+ * so a count here would always be zero, which reads as an answer.+ */+ server_removed: {+ server_kind: 'local' | 'remote_managed' | 'external';+ };+ /**+ * A session whose setup had not completed was provisioned again.+ *+ * The first attempt for a session is not reported: what is worth knowing is+ * whether a second one worked, and whether anyone had to ask for it.+ */+ session_provision_retried: {+ agent_type: TelemetryAgentType;+ location: TelemetryLocationKind;+ trigger: TelemetrySessionProvisionTrigger;+ outcome: TelemetryOutcome;+ };+ /**+ * A remote session's terminal was attached, or could not be.+ *+ * Reported only for an attach a person waited on. A transport drop cancels+ * every queued attach at once, which is one failure rather than a host's+ * worth, so a cancelled attach is not reported as one.+ */+ session_attached: {+ agent_type: TelemetryAgentType;+ outcome: TelemetryOutcome;+ };+ /**+ * An agent's own CLI was installed, updated or removed — not the Switch+ * connector, which `connector_installed` and friends report.+ *+ * The single biggest wall a new user hits, and until now entirely uncounted.+ */+ agent_cli_action: {+ agent_type: TelemetryAgentType;+ target: 'local' | 'remote';+ install_method: TelemetryInstallMethod;+ action: TelemetryCliAction;+ outcome: TelemetryOutcome;+ failure_reason: TelemetryCliFailure;+ };+ /**+ * A room was created on a server. `bridge_unavailable` is the failure worth+ * watching: it means the messaging platform, not the app, refused.+ */+ room_created: {+ server_kind: TelemetryServerKind;+ bridge_platform: TelemetryBridgePlatform;+ agent_count: number;+ has_instructions: boolean;+ outcome: TelemetryOutcome;+ failure_reason: TelemetryRoomCreateFailure;+ };+ room_deleted: {+ server_kind: TelemetryServerKind;+ outcome: TelemetryOutcome;+ };+ room_agents_added: {+ agent_count: number;+ direction: TelemetryRoomAgentsDirection;+ };+ /** Someone signed in to a server. */+ server_sign_in: {+ auth_method: TelemetryAuthMethod;+ server_kind: TelemetryServerKind;+ outcome: TelemetryOutcome;+ failure_reason: TelemetrySignInFailure;+ };+ server_sign_out: {+ server_kind: TelemetryServerKind;+ };+ /**+ * A step of a remote host's setup was run.+ *+ * A skip is worth counting separately from a failure: it is someone deciding+ * to go on without the thing, which is an abandonment signal rather than a+ * fault.+ */+ host_setup_step: {+ step_kind: TelemetryHostSetupStepKind;+ agent_type: TelemetryAgentType;+ action: TelemetryHostSetupAction;+ outcome: TelemetryOutcome;+ };+ host_onboarded: {+ outcome: TelemetryOutcome;+ /** Whether the host was picked from the machine's SSH config or typed in. */+ picked_from_ssh_config: boolean;+ };+ host_removed: {+ outcome: TelemetryOutcome;+ };+ /**+ * A managed Switch server was started, stopped or reset.+ *+ * Docker missing or refusing is the classic first-run wall, and starting one+ * already probes for it — so the dimension that explains the failure comes+ * free on the path where it matters.+ */+ managed_server_action: {+ action: TelemetryManagedServerAction;+ target: 'local' | 'remote';+ outcome: TelemetryOutcome;+ failure_reason: TelemetryManagedServerFailure;+ docker_available: TelemetryDockerAvailability;+ };+ /**+ * The four events below are reported by the interface, through the one gate in+ * `./renderer-events`. They are here because they are catalogue events like+ * any other — the same consent check, the same property filter — and only the+ * place they are observed differs.+ */+ view_opened: RendererTelemetryEvents['view_opened'];+ command_executed: RendererTelemetryEvents['command_executed'];+ deeplink_opened: RendererTelemetryEvents['deeplink_opened'];+ onboarding_step_started: RendererTelemetryEvents['onboarding_step_started'];+ onboarding_checklist_dismissed: RendererTelemetryEvents['onboarding_checklist_dismissed'];+ onboarding_completed: RendererTelemetryEvents['onboarding_completed'];+ add_server_step: RendererTelemetryEvents['add_server_step'];+ /** A screen failed. A count, with nothing of what failed or where. */+ renderer_crashed: RendererTelemetryEvents['renderer_crashed'];+ /**+ * A setting was changed. **The key only, never the value.** Several settings+ * hold free text — a sound file, a default directory, a font, a browser+ * profile — and the useful question is which settings people touch, which the+ * key answers on its own.+ */+ setting_changed: {+ setting_key: TelemetrySettingKey;+ };+ /**+ * A search ran. Never the query: what is asked for is the user's, and the+ * answerable questions are whether search finds anything and what people open.+ */+ search_performed: {+ /**+ * The search's own outcome union, which already separates the four cases+ * that matter — including a search that failed, which is not the same as one+ * that found nothing.+ */+ status: TelemetrySearchStatus;+ result_count: number;+ };+ /**+ * Consent to share usage data was switched **on**.+ *+ * Only on. Turning it off cannot be reported — the gate is read immediately+ * before every send, so by the time the setting is written the event is+ * already blocked — and reporting a refusal would mean transmitting something+ * from someone at the moment they asked us not to. So the opt-out rate is+ * deliberately unknown rather than obtained that way, and this counts the+ * agreements only. `first_run` is the prompt on first launch; `settings` is+ * someone turning it on later of their own accord.+ */+ telemetry_consent_changed: {+ source: 'first_run' | 'settings';+ };};export type TelemetryEventName = keyof TelemetryEventMap;@@ -85,13 +589,97 @@ export type TelemetryEventName = keyof TelemetryEventMap;*/export const TELEMETRY_EVENT_PROPERTIES = {app_launched: [],- agent_created: ['agent_type', 'location'],- session_started: ['agent_type', 'location'],+ agent_created: ['agent_type', 'location', 'outcome', 'failure_reason', 'entry_point'],+ session_started: [+ 'agent_type',+ 'location',+ 'outcome',+ 'failure_reason',+ 'entry_point',+ 'start_source',+ 'has_initial_prompt',+ 'connected_to_room',+ ],session_ended: ['agent_type', 'location', 'outcome'],- server_added: ['server_kind'],+ server_added: ['server_kind', 'outcome'],connector_installed: ['agent_type', 'target', 'outcome'],+ update_checked: ['trigger', 'result'],+ update_downloaded: ['outcome'],+ update_install_started: ['outcome'],+ bridge_connected: ['bridge_platform', 'outcome', 'failure_reason'],+ bridge_disconnected: ['bridge_platform', 'outcome'],+ bridge_identity_claimed: ['bridge_platform', 'outcome'],+ connector_updated: ['agent_type', 'target', 'outcome', 'was_reinstall'],+ connector_uninstalled: ['agent_type', 'target', 'outcome'],+ agent_removed: [+ 'agent_type',+ 'location',+ 'delete_in_switch',+ 'trigger',+ 'outcome',+ 'failure_reason',+ ],+ agent_reset: ['agent_type', 'outcome', 'failure_reason'],+ server_removed: ['server_kind'],+ session_provision_retried: ['agent_type', 'location', 'trigger', 'outcome'],+ setting_changed: ['setting_key'],+ search_performed: ['status', 'result_count'],+ agent_cli_action: [+ 'agent_type',+ 'target',+ 'install_method',+ 'action',+ 'outcome',+ 'failure_reason',+ ],+ room_created: [+ 'server_kind',+ 'bridge_platform',+ 'agent_count',+ 'has_instructions',+ 'outcome',+ 'failure_reason',+ ],+ room_deleted: ['server_kind', 'outcome'],+ room_agents_added: ['agent_count', 'direction'],+ server_sign_in: ['auth_method', 'server_kind', 'outcome', 'failure_reason'],+ server_sign_out: ['server_kind'],+ host_setup_step: ['step_kind', 'agent_type', 'action', 'outcome'],+ host_onboarded: ['outcome', 'picked_from_ssh_config'],+ host_removed: ['outcome'],+ managed_server_action: ['action', 'target', 'outcome', 'failure_reason', 'docker_available'],+ view_opened: ['view_id'],+ command_executed: ['command_id', 'invoked_by'],+ deeplink_opened: ['resolved', 'cold_start'],+ onboarding_step_started: ['step_id'],+ onboarding_checklist_dismissed: [],+ onboarding_completed: [],+ add_server_step: ['step', 'choice'],+ renderer_crashed: [],+ telemetry_consent_changed: ['source'],+ session_attached: ['agent_type', 'outcome'],} as const satisfies { [K in TelemetryEventName]: readonly (keyof TelemetryEventMap[K])[] };+/**+ * Any catalogued property the allow-list above leaves out.+ *+ * The `satisfies` clause constrains what may appear in each array — every entry+ * has to be a real property of that event — but says nothing about what must.+ * A property added to the map and forgotten here therefore compiles, and is+ * dropped at runtime by the emitter: the event still sends, minus a dimension,+ * with nothing to say so. The mechanical walk in `./catalogue.test.ts` cannot+ * catch it either, since it builds its samples from this list.+ */+type UndeclaredProperty = {+ [K in TelemetryEventName]: Exclude<+ keyof TelemetryEventMap[K],+ (typeof TELEMETRY_EVENT_PROPERTIES)[K][number]+ >;+}[TelemetryEventName];++const _everyPropertyIsAllowListed: [UndeclaredProperty] extends [never] ? true : never = true;+void _everyPropertyIsAllowListed;+/** Which events, if any, declare a property the emitter also adds. */type EventsDeclaringAmbientProperty = {[K in TelemetryEventName]: 'build' extends keyof TelemetryEventMap[K] ? K : never;diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/managed-server.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/managed-server.tsnew file mode 100644index 000000000..1b9a95aa5--- /dev/null+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/managed-server.ts@@ -0,0 +1,92 @@+import type { StartLocalServerResult } from '@shared/core/managed-switch-server/managed-switch-server';+import type { TelemetryManagedServerAction, TelemetryManagedServerFailure } from './events';+import { trackEvent } from './telemetry-service';++/**+ * What starting, stopping or resetting a managed server reported.+ *+ * One place rather than six near-identical blocks across the local and remote+ * services, whose only real difference is which of the two they are.+ */++/** A start's own result union, as a reportable code. */+function startFailureReason(result: StartLocalServerResult): TelemetryManagedServerFailure {+ switch (result.kind) {+ case 'started':+ return 'none';+ case 'docker-unavailable':+ return result.reason === 'not-installed' ? 'docker_not_installed' : 'docker_daemon_down';+ case 'version-downgrade':+ return 'version_downgrade';+ case 'error':+ return 'error';+ }+}++/**+ * Report a start.+ *+ * Starting is the only one of the three that probes for Docker, so it is the+ * only one that can answer whether Docker was there — which is exactly the+ * question worth asking, since Docker missing or refusing is the wall most+ * first-run failures hit.+ */+export function reportManagedServerStart(+ target: 'local' | 'remote',+ result: StartLocalServerResult+): void {+ trackEvent('managed_server_action', {+ action: 'start',+ target,+ outcome: result.kind === 'started' ? 'success' : 'failure',+ failure_reason: startFailureReason(result),+ // Safe to read the probe off the result: every one of these comes back from+ // the pipeline, whose first act is to look for Docker. A start that never+ // got that far does not come through here — see below.+ docker_available: result.kind === 'docker-unavailable' ? 'unavailable' : 'available',+ });+}++/**+ * Report a start that threw.+ *+ * Kept apart from the function above because the difference is the whole point:+ * a thrown start may have failed before the pipeline ran, and on the remote path+ * routinely does — opening the SSH connection comes first, and an unreachable+ * host fails there. Feeding a synthesised `error` result to the reporter above+ * would answer `available` for a start that never looked, which is exactly the+ * guess this dimension exists to avoid.+ */+export function reportManagedServerStartThrew(target: 'local' | 'remote'): void {+ trackEvent('managed_server_action', {+ action: 'start',+ target,+ outcome: 'failure',+ failure_reason: 'error',+ docker_available: 'unknown',+ });+}++/**+ * Report a stop or a reset.+ *+ * Neither probes for Docker, so neither can say whether it was available, and+ * `unknown` is the honest answer rather than adding a round trip — on the remote+ * path, an SSH one — to a teardown that does not otherwise need it.+ *+ * Both signal failure by throwing, so there is no result union to read: the+ * caller reports which of the two happened.+ */+export function reportManagedServerOutcome(+ action: Exclude<TelemetryManagedServerAction, 'start'>,+ target: 'local' | 'remote',+ outcome: 'success' | 'failure'+): void {+ trackEvent('managed_server_action', {+ action,+ target,+ outcome,+ failure_reason: outcome === 'success' ? 'none' : 'error',+ docker_available: 'unknown',+ });+}diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/narrow.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/narrow.tsnew file mode 100644index 000000000..bc9d4eb4a--- /dev/null+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/narrow.ts@@ -0,0 +1,78 @@+import { INSTALL_METHODS } from '@switch-console/core/deps';+import {+ AGENT_REMOVE_TRIGGERS,+ ROOM_AGENTS_DIRECTIONS,+ SESSION_PROVISION_TRIGGERS,+ SESSION_START_SOURCES,+ UI_ENTRY_POINTS,+ UPDATE_TRIGGERS,+} from '@shared/core/telemetry/reporting';+import type {+ TelemetryAgentRemoveTrigger,+ TelemetryEntryPoint,+ TelemetryInstallMethod,+ TelemetryRoomAgentsDirection,+ TelemetrySessionProvisionTrigger,+ TelemetrySessionStartSource,+ TelemetryUpdateTrigger,+} from './events';++/**+ * Dimensions the interface supplies, checked rather than trusted.+ *+ * The events the renderer reports directly go through a schema in+ * `./renderer-events`, on the stated grounds that a type does not survive a+ * process boundary. These values cross the same boundary — they ride along on+ * ordinary operations like "add this agent" or "retry this session" — and the+ * reasoning does not stop applying because the event is emitted from the main+ * process. Nothing validates an RPC argument at the boundary itself, so this is+ * where it happens.+ *+ * Every one falls back rather than throwing. A wrong value is a bug in a call+ * site, not something to fail a user's operation over — and reporting it as+ * unrecognised is what makes the bug visible instead of putting free text in a+ * payload.+ */++function oneOf<T extends string>(allowed: readonly T[], value: unknown, fallback: T): T {+ return typeof value === 'string' && (allowed as readonly string[]).includes(value)+ ? (value as T)+ : fallback;+}++export function entryPointOf(value: unknown): TelemetryEntryPoint {+ return oneOf(UI_ENTRY_POINTS, value, 'unknown');+}++/**+ * `unknown` rather than `user`: every other fallback here reports the absence of+ * a claim, and `user` would report the presence of one — asserting a person was+ * behind a session on the strength of a caller that said nothing.+ */+export function startSourceOf(value: unknown): TelemetrySessionStartSource {+ return oneOf(SESSION_START_SOURCES, value, 'unknown');+}++/**+ * `initial` is the honest fallback: an unrecognised trigger is not evidence+ * anybody retried anything, and `initial` is the value that reports nothing.+ */+export function provisionTriggerOf(value: unknown): TelemetrySessionProvisionTrigger | 'initial' {+ return oneOf(SESSION_PROVISION_TRIGGERS, value, 'initial');+}++export function agentRemoveTriggerOf(value: unknown): TelemetryAgentRemoveTrigger {+ return oneOf(AGENT_REMOVE_TRIGGERS, value, 'user');+}++export function roomAgentsDirectionOf(value: unknown): TelemetryRoomAgentsDirection {+ return oneOf(ROOM_AGENTS_DIRECTIONS, value, 'agents_to_room');+}++export function updateTriggerOf(value: unknown): TelemetryUpdateTrigger {+ return oneOf(UPDATE_TRIGGERS, value, 'user');+}++export function installMethodOf(value: unknown): TelemetryInstallMethod {+ return oneOf<TelemetryInstallMethod>([...INSTALL_METHODS, 'unspecified'], value, 'unspecified');+}diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/relay-client.test.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/relay-client.test.tsindex 844683d05..73286b1a7 100644--- a/console/apps/switch-console-desktop/src/main/core/telemetry/relay-client.test.ts+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/relay-client.test.ts@@ -42,6 +42,23 @@ function logAttributes(payload: Record<string, unknown>): Record<string, string>return Object.fromEntries(attributes.map((a) => [a.key, a.value.stringValue]));}+/** The attribute values as OTLP actually carries them, kind and all. */+function rawLogAttributes(payload: Record<string, unknown>): Record<string, unknown> {+ const attributes = logRecord(payload).attributes as { key: string; value: unknown }[];+ return Object.fromEntries(attributes.map((a) => [a.key, a.value]));+}++const SESSION_STARTED = {+ agent_type: 'codex',+ location: 'local',+ outcome: 'success',+ failure_reason: 'none',+ entry_point: 'sidebar',+ start_source: 'user',+ has_initial_prompt: false,+ connected_to_room: false,+} as const;+describe('the record that gets built', () => {it('carries the client id the relay requires, as a resource attribute', () => {// Without it the relay drops the whole payload — and still answers 200.@@ -63,11 +80,7 @@ describe('the record that gets built', () => {});it('names the event under this product, since one project holds them all', () => {- const payload = buildOtlpPayload(- 'session_started',- { agent_type: 'codex', location: 'local' },- CONTEXT- );+ const payload = buildOtlpPayload('session_started', SESSION_STARTED, CONTEXT);expect(logAttributes(payload)['event.name']).toBe('switch_console.session_started');});@@ -141,6 +154,34 @@ describe('the record that gets built', () => {);});+ it('carries a yes/no as a boolean, not as the word "false"', () => {+ // A string "false" is truthy everywhere it lands, so a flag sent that way+ // reads as always-true in the one place anybody looks at it.+ const payload = buildOtlpPayload('session_started', SESSION_STARTED, CONTEXT);++ expect(rawLogAttributes(payload).has_initial_prompt).toEqual({ boolValue: false });+ expect(rawLogAttributes(payload).connected_to_room).toEqual({ boolValue: false });+ });++ it('carries a count as a number, so it can be summed at the far end', () => {+ const payload = buildOtlpPayload(+ 'session_started',+ { ...SESSION_STARTED, has_initial_prompt: true },+ CONTEXT+ );++ expect(rawLogAttributes(payload).has_initial_prompt).toEqual({ boolValue: true });+ expect(rawLogAttributes(payload).entry_point).toEqual({ stringValue: 'sidebar' });+ });++ it('refuses a count that is not a real number rather than sending null', () => {+ // NaN and Infinity both serialise to `null` in JSON, which at the far end+ // is indistinguishable from a property that was never sent.+ const broken = { ...SESSION_STARTED, has_initial_prompt: Number.NaN } as never;++ expect(() => buildOtlpPayload('session_started', broken, CONTEXT)).toThrow(/non-finite/);+ });+it('stamps the time in nanoseconds, which is what OTLP counts in', () => {const payload = buildOtlpPayload('app_launched', {}, CONTEXT);diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/relay-client.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/relay-client.tsindex 78d7a3b83..8dcaeced1 100644--- a/console/apps/switch-console-desktop/src/main/core/telemetry/relay-client.ts+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/relay-client.ts@@ -72,11 +72,35 @@ export type TelemetryContext = {timeMs: number;};-type OtlpAttribute = { key: string; value: { stringValue: string } };+/**+ * What a catalogued property may be, once it is data rather than a type.+ *+ * The three kinds the catalogue allows: an enumerated string, a count, and a+ * yes/no. Not an object, not an array, not null — anything else is a bug in a+ * call site rather than a value to find an encoding for.+ */+type TelemetryValue = string | number | boolean;-/** Everything sent is a string; nothing in the catalogue is anything else. */-function attributes(values: Record<string, string>): OtlpAttribute[] {- return Object.entries(values).map(([key, value]) => ({ key, value: { stringValue: value } }));+type OtlpValue = { stringValue: string } | { boolValue: boolean } | { doubleValue: number };++type OtlpAttribute = { key: string; value: OtlpValue };++/**+ * A property in the shape OTLP carries it.+ *+ * Numbers go as `doubleValue` rather than `intValue`: OTLP's int64 is a string+ * in JSON, which invites a receiver to treat a count as text and makes it+ * useless to average. Every count in the catalogue is small and exact as a+ * double, so nothing is lost by not distinguishing the two.+ */+function otlpValue(value: TelemetryValue): OtlpValue {+ if (typeof value === 'boolean') return { boolValue: value };+ if (typeof value === 'number') return { doubleValue: value };+ return { stringValue: value };+}++function attributes(values: Record<string, TelemetryValue>): OtlpAttribute[] {+ return Object.entries(values).map(([key, value]) => ({ key, value: otlpValue(value) }));}/**@@ -90,19 +114,26 @@ function attributes(values: Record<string, string>): OtlpAttribute[] {function allowedProperties<K extends TelemetryEventName>(name: K,properties: TelemetryEventMap[K]-): Record<string, string> {- const allowed: Record<string, string> = {};+): Record<string, TelemetryValue> {+ const allowed: Record<string, TelemetryValue> = {};for (const key of TELEMETRY_EVENT_PROPERTIES[name]) {const value = (properties as Record<string, unknown>)[key];// Coercing a missing property would send the string "undefined" as though// it were data. Refusing means the event is dropped and the mismatch is- // logged, which is the lesser of the two.- if (typeof value !== 'string') {+ // logged, which is the lesser of the two. `null` and `undefined` both fail+ // here, as does anything structured — an object reaching a payload is how a+ // field nobody catalogued gets sent.+ if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') {throw new TelemetrySendError('unexpected',`Event ${name} is missing the catalogued property ${key}`);}+ // A number that is not a real number has no meaning at the far end and+ // would serialise to `null`, silently turning a count into an absence.+ if (typeof value === 'number' && !Number.isFinite(value)) {+ throw new TelemetrySendError('unexpected', `Event ${name} has a non-finite value for ${key}`);+ }allowed[key] = value;}return allowed;diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/renderer-events.test.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/renderer-events.test.tsnew file mode 100644index 000000000..dc32014ec--- /dev/null+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/renderer-events.test.ts@@ -0,0 +1,282 @@+import { beforeEach, describe, expect, it, vi } from 'vitest';++/**+ * The gate between the interface and the catalogue.+ *+ * This is the only place a telemetry value arrives from outside the main+ * process, so it is the only place a type proves nothing. These cover that the+ * check is real: the list of events is closed, and every value is checked+ * against the set the catalogue allows rather than taken on the caller's word.+ */++const { store, canSend, UNREADABLE, UNWRITABLE } = vi.hoisted(() => ({+ store: new Map<string, boolean>(),+ canSend: vi.fn(async () => true),+ /**+ * Set this key and reads of the record fail. Reading it is a database read in+ * the real thing, and a database read can fail — the only way into the branch+ * that decides what to do when the record cannot be read.+ */+ UNREADABLE: '__unreadable__',+ /**+ * The same for writes. The claim is written with `setOrThrow` rather than+ * `set`, precisely so a failed write is not silently treated as a claim, so+ * this branch is reachable too.+ */+ UNWRITABLE: '__unwritable__',+}));++vi.mock('./telemetry-service', () => ({+ trackEvent: vi.fn(),+ telemetryService: { canSend },+}));+// The once-per-install record. Backed by the database in the real thing, which+// this project has no Electron app to open.+vi.mock('@main/db/kv', () => ({+ KV: class {+ get(key: string) {+ if (store.get(UNREADABLE) === true) return Promise.reject(new Error('kv: read failed'));+ return Promise.resolve(store.get(key) ?? null);+ }+ set(key: string, value: boolean) {+ store.set(key, value);+ return Promise.resolve();+ }+ setOrThrow(key: string, value: boolean) {+ if (store.get(UNWRITABLE) === true) return Promise.reject(new Error('kv: write failed'));+ store.set(key, value);+ return Promise.resolve();+ }+ },+}));+vi.mock('@main/lib/logger', () => ({+ log: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },+}));++const { trackFromRenderer } = await import('./renderer-events');+const { trackEvent } = await import('./telemetry-service');+const { log } = await import('@main/lib/logger');++beforeEach(() => {+ vi.clearAllMocks();+ store.clear();+ canSend.mockResolvedValue(true);+});++/** The once-only path settles on a promise, so let it. */+const settle = () => new Promise((resolve) => setTimeout(resolve, 0));++describe('what the interface is allowed to report', () => {+ it('passes a catalogued event with permitted values through to the emitter', () => {+ trackFromRenderer({ name: 'view_opened', properties: { view_id: 'settings' } });++ expect(trackEvent).toHaveBeenCalledWith('view_opened', { view_id: 'settings' });+ });++ it('refuses an event that is not on the list', () => {+ // The renderer may report the handful of moments only it can see. Anything+ // else is a call site and this list disagreeing, which is a bug in the app.+ trackFromRenderer({+ name: 'agent_created' as never,+ properties: { agent_type: 'codex' },+ });++ expect(trackEvent).not.toHaveBeenCalled();+ expect(log.warn).toHaveBeenCalled();+ });++ it('refuses a value the catalogue does not allow', () => {+ // The whole reason this exists: a type does not survive the crossing, so a+ // screen id that is not one of the app's screens must be caught here.+ trackFromRenderer({ name: 'view_opened', properties: { view_id: 'not-a-view' } });++ expect(trackEvent).not.toHaveBeenCalled();+ });++ it('refuses free text where a closed set is expected', () => {+ trackFromRenderer({+ name: 'command_executed',+ properties: { command_id: '/Users/someone/secret-project', invoked_by: 'palette' },+ });++ expect(trackEvent).not.toHaveBeenCalled();+ });++ it('never writes down the value it rejected', () => {+ // A value that failed this check is exactly the kind of thing that must not+ // reach the log either.+ trackFromRenderer({+ name: 'view_opened',+ properties: { view_id: '/Users/someone/secret-project' },+ });++ expect(JSON.stringify(vi.mocked(log.warn).mock.calls)).not.toContain('secret-project');+ });++ it('drops a property the event does not declare', () => {+ trackFromRenderer({+ name: 'view_opened',+ properties: { view_id: 'home', working_dir: '/Users/someone/secret-project' },+ });++ expect(trackEvent).toHaveBeenCalledWith('view_opened', { view_id: 'home' });+ });++ it('accepts an event that carries nothing of its own', () => {+ trackFromRenderer({ name: 'renderer_crashed', properties: {} });++ expect(trackEvent).toHaveBeenCalledWith('renderer_crashed', {});+ });++ it('refuses a missing property rather than sending the event without it', () => {+ trackFromRenderer({ name: 'command_executed', properties: { invoked_by: 'palette' } });++ expect(trackEvent).not.toHaveBeenCalled();+ });++ it('checks a command id against the commands that exist', () => {+ trackFromRenderer({+ name: 'command_executed',+ properties: { command_id: 'app.settings', invoked_by: 'shortcut' },+ });++ expect(trackEvent).toHaveBeenCalledWith('command_executed', {+ command_id: 'app.settings',+ invoked_by: 'shortcut',+ });+ });++ it('still reports an ordinary event every time it happens', async () => {+ trackFromRenderer({ name: 'view_opened', properties: { view_id: 'home' } });+ trackFromRenderer({ name: 'view_opened', properties: { view_id: 'settings' } });+ await settle();++ expect(trackEvent).toHaveBeenCalledTimes(2);+ });++ it('does not ask the gate in advance for an ordinary event', async () => {+ // Only an event that spends a record has anything to lose by being refused.+ // Everywhere else, asking first and sending second reads a gate that can+ // change in between, and the emitter already reads it at the one moment that+ // matters.+ trackFromRenderer({ name: 'view_opened', properties: { view_id: 'home' } });+ await settle();++ expect(canSend).not.toHaveBeenCalled();+ expect(trackEvent).toHaveBeenCalledTimes(1);+ });+});++/**+ * Finishing onboarding is a condition, not a moment — true from the instant it+ * becomes true and true again on every launch. Each test takes a fresh copy of+ * the module, because "already reported in this run" is deliberately process+ * state: one run of the app is one chance to report.+ *+ * The record is never given back, so as much of what follows is about when it is+ * *not* spent as about when it is.+ */+describe('an event reported once per install', () => {+ async function freshGate() {+ vi.resetModules();+ const mod = await import('./renderer-events');+ return mod.trackFromRenderer;+ }++ beforeEach(() => {+ vi.clearAllMocks();+ store.clear();+ canSend.mockResolvedValue(true);+ });++ it('reports once however many times the interface asks', async () => {+ const gate = await freshGate();++ gate({ name: 'onboarding_completed', properties: {} });+ gate({ name: 'onboarding_completed', properties: {} });+ gate({ name: 'onboarding_completed', properties: {} });+ await settle();++ expect(trackEvent).toHaveBeenCalledTimes(1);+ });++ it('writes down that it reported, so a later run stays quiet', async () => {+ const first = await freshGate();+ first({ name: 'onboarding_completed', properties: {} });+ await settle();+ expect(trackEvent).toHaveBeenCalledTimes(1);+ vi.mocked(trackEvent).mockClear();++ // A new run of the app: fresh process state, same stored record.+ const later = await freshGate();+ later({ name: 'onboarding_completed', properties: {} });+ await settle();++ expect(trackEvent).not.toHaveBeenCalled();+ });++ it('stays quiet rather than reporting twice when the record cannot be read', async () => {+ // A duplicate is the failure this exists to prevent, so a record we cannot+ // read is treated as one that might already say yes.+ store.set(UNREADABLE, true);+ const gate = await freshGate();++ gate({ name: 'onboarding_completed', properties: {} });+ await settle();+ gate({ name: 'onboarding_completed', properties: {} });+ await settle();++ expect(trackEvent).not.toHaveBeenCalled();+ });++ it('has not spent the record on a read that failed', async () => {+ store.set(UNREADABLE, true);+ const failed = await freshGate();+ failed({ name: 'onboarding_completed', properties: {} });+ await settle();+ expect(trackEvent).not.toHaveBeenCalled();++ // Nothing was written, so the next run of the app is a fresh chance rather+ // than a run that inherits a record nobody managed to make.+ store.delete(UNREADABLE);+ const later = await freshGate();+ later({ name: 'onboarding_completed', properties: {} });+ await settle();++ expect(trackEvent).toHaveBeenCalledTimes(1);+ });++ it('stays quiet rather than reporting without a record it could keep', async () => {+ // A write that failed leaves nothing to stop the next run reporting again,+ // so sending anyway buys one report at the price of a duplicate. The same+ // trade as the unreadable record above, made the same way.+ store.set(UNWRITABLE, true);+ const gate = await freshGate();++ gate({ name: 'onboarding_completed', properties: {} });+ await settle();++ expect(trackEvent).not.toHaveBeenCalled();+ });++ it('claims nothing while a send would be refused, so it can still be reported', async () => {+ // The app renders behind the first-run consent prompt, so an install that+ // already has a server, an agent and a room reports a finished checklist+ // while the answer is still unset. Spending the record there would retire the+ // event for the life of the install.+ canSend.mockResolvedValue(false);+ const gate = await freshGate();++ gate({ name: 'onboarding_completed', properties: {} });+ await settle();++ expect(trackEvent).not.toHaveBeenCalled();+ expect(store.size).toBe(0);++ canSend.mockResolvedValue(true);+ gate({ name: 'onboarding_completed', properties: {} });+ await settle();++ expect(trackEvent).toHaveBeenCalledTimes(1);+ });+});diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/renderer-events.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/renderer-events.tsnew file mode 100644index 000000000..844be6f70--- /dev/null+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/renderer-events.ts@@ -0,0 +1,227 @@+import { z } from 'zod';+import { KV } from '@main/db/kv';+import { log } from '@main/lib/logger';+import { ALL_COMMAND_DEFS, type CommandId } from '@shared/commands';+import { ONBOARDING_STEP_IDS } from '@shared/core/onboarding/checklist';+import { ADD_SERVER_CHOICES, ADD_SERVER_STEPS } from '@shared/core/switch-servers/add-server-steps';+import { VIEW_IDS } from '@shared/core/views/view-ids';+import type { TelemetryEventMap, TelemetryEventName } from './events';+import { telemetryService, trackEvent } from './telemetry-service';++/**+ * The command ids that exist, as a set to check a received value against.+ *+ * Derived from the definitions rather than listed again: the ids are already+ * written down once, and a second copy is a second thing to forget.+ */+const COMMAND_IDS = new Set<string>(ALL_COMMAND_DEFS.map((c) => c.id));++const commandId = z.custom<CommandId>(+ (value) => typeof value === 'string' && COMMAND_IDS.has(value)+);++/**+ * The events the user interface may ask for, and the only values it may supply.+ *+ * Most of what the app reports happens in the main process, where a call site is+ * type-checked against the catalogue and reviewed. These are the exceptions:+ * moments that exist only in the interface — which screen was opened, which+ * command was run, where someone stopped in a checklist — and there is no way to+ * observe them from the other side.+ *+ * This is a gate, not a second emitter. Nothing here builds or sends a payload:+ * a validated call goes to the same `trackEvent`, the same consent check and the+ * same property filter as every other event. What it adds is the one thing the+ * main process cannot take on trust — that a value which crossed a process+ * boundary is still one of the values the catalogue allows. A type does not+ * survive that crossing; these schemas are what replaces it.+ *+ * Adding an event here is therefore a wider decision than adding one in the main+ * process, and the list is meant to stay short. If a moment can be observed from+ * the main process, observe it there.+ */+const RENDERER_TELEMETRY_SCHEMAS = {+ view_opened: z.object({ view_id: z.enum(VIEW_IDS) }),+ command_executed: z.object({+ command_id: commandId,+ invoked_by: z.enum(['palette', 'shortcut']),+ }),+ deeplink_opened: z.object({ resolved: z.boolean(), cold_start: z.boolean() }),+ onboarding_step_started: z.object({ step_id: z.enum(ONBOARDING_STEP_IDS) }),+ onboarding_checklist_dismissed: z.object({}),+ onboarding_completed: z.object({}),+ add_server_step: z.object({+ step: z.enum(ADD_SERVER_STEPS),+ choice: z.enum(ADD_SERVER_CHOICES),+ }),+ renderer_crashed: z.object({}),+} as const satisfies {+ [K in RendererTelemetryEvent]: z.ZodType<TelemetryEventMap[K]>;+};++/**+ * What this gate lets through is exactly what the catalogue declares.+ *+ * Comparing `RendererTelemetryEvents` to `TelemetryEventMap` would prove+ * nothing — the catalogue *defines* those eight events as the shared shapes+ * (see `./events`), so the two sides are the same type by construction and any+ * such assertion is a tautology. The pair that can genuinely disagree is the+ * schema and the shape: a schema is hand-written, and one that forgets a+ * property parses a payload without it, strips it, and reports an event missing+ * a dimension.+ *+ * So the check is on the schemas' *output*. The `satisfies` above already+ * refuses a schema that omits a required property; this refuses the other+ * direction, a schema that admits one the catalogue does not declare.+ *+ * Written as `[X] extends [never]` rather than indexing the map by the union:+ * an indexed access distributes and then collapses, so `true | never` is `true`+ * and only an *every* event mismatch would fail. That is how the assertion this+ * replaces passed while being wrong.+ *+ * Read off `shape` rather than `z.infer`, which widens the two property-less+ * schemas to a `keyof` of `string` — a check whose failure mode is "every event+ * looks wrong" is no more use than one that never fails.+ */+type SchemaExtra = {+ [K in RendererTelemetryEvent]: Exclude<+ keyof (typeof RENDERER_TELEMETRY_SCHEMAS)[K]['shape'],+ keyof TelemetryEventMap[K]+ >;+}[RendererTelemetryEvent];++const _schemasAddNothing: [SchemaExtra] extends [never] ? true : never = true;+void _schemasAddNothing;++/** Every event the interface may report is one the catalogue knows about. */+const _rendererEventsAreCatalogued: [Exclude<RendererTelemetryEvent, TelemetryEventName>] extends [+ never,+]+ ? true+ : never = true;+void _rendererEventsAreCatalogued;++/**+ * The events the interface is allowed to report.+ *+ * Named as a union rather than derived from the schema map, so that widening the+ * map is a deliberate edit in two places rather than a side effect of adding a+ * schema.+ */+export type RendererTelemetryEvent =+ | 'view_opened'+ | 'command_executed'+ | 'deeplink_opened'+ | 'onboarding_step_started'+ | 'onboarding_completed'+ | 'onboarding_checklist_dismissed'+ | 'add_server_step'+ | 'renderer_crashed';++export type RendererTelemetryRequest = {+ name: RendererTelemetryEvent;+ properties: Record<string, unknown>;+};++/**+ * Events that describe a state rather than a moment, and so are reported once+ * for the life of an install.+ *+ * Finishing onboarding is the case this exists for: it is derived from a server+ * and a room existing, so it is true from the instant it becomes true and true+ * again on every later launch. Without this it would be counted once per+ * start-up forever, and "people who finished setting up" would grow without+ * anyone finishing anything.+ *+ * The record lives here, beside the emitter, rather than in the user's settings:+ * it is our bookkeeping, and writing it as a setting would report a setting the+ * user never changed.+ */+const ONCE_PER_INSTALL = new Set<RendererTelemetryEvent>(['onboarding_completed']);++const reportedOnce = new KV<Record<string, boolean>>('telemetry:reported');++/**+ * Whether this once-only event has already been sent, claiming it if not.+ *+ * The in-memory guard matters as much as the stored one: the renderer can ask+ * several times in the same tick — a condition becoming true re-renders+ * everything watching it — and the database write does not land in time to stop+ * the second caller.+ *+ * The consent check comes first, and is the reason this is not simply a claim.+ * The record is never given back, so claiming before the gate spends it on a+ * send the gate then discards — and the event is retired for the life of the+ * install. That is not a corner case: the app renders behind the first-run+ * consent prompt, so on the very first launch of a build the interface reports+ * a finished checklist while the answer is still unset, which is `no` until it+ * is `yes`. Every install that already had a server, an agent and a room would+ * have burned the record before anyone could agree to anything.+ *+ * Nothing is claimed while a send would be refused, so the event stays available+ * and is reported the next time the condition holds and consent is in place.+ */+const claimedThisRun = new Set<RendererTelemetryEvent>();++async function claimOnce(name: RendererTelemetryEvent): Promise<boolean> {+ if (claimedThisRun.has(name)) return false;+ if (!(await telemetryService.canSend())) return false;+ if (claimedThisRun.has(name)) return false;+ claimedThisRun.add(name);+ if ((await reportedOnce.get(name)) === true) return false;+ // `setOrThrow`, because the ordinary `set` logs a failed write and returns:+ // the caller would then send the event with no durable record of having done+ // so, and report it again on the next launch. Letting the write throw hands+ // the decision to the caller below, which keeps this run quiet and leaves the+ // record unclaimed for the next one — a report that may be missed, rather+ // than one that is certainly duplicated.+ await reportedOnce.setOrThrow(name, true);+ return true;+}++/**+ * Report an event the interface observed, if it is one it may report.+ *+ * A request naming an event that is not on the list, or carrying a value that is+ * not one the catalogue allows, is dropped rather than sent — and said out loud,+ * because it means a call site and this list disagree, which is a bug in the app+ * and not something a user should be transmitting on behalf of.+ */+export function trackFromRenderer(request: RendererTelemetryRequest): void {+ const schema = RENDERER_TELEMETRY_SCHEMAS[request.name];+ if (!schema) {+ log.warn('telemetry: renderer asked for an event it may not send', {+ event: 'telemetry_renderer_rejected',+ telemetryEvent: request.name,+ reason: 'not_permitted',+ });+ return;+ }++ const parsed = schema.safeParse(request.properties);+ if (!parsed.success) {+ // The values are deliberately not logged: a value that failed this check is+ // exactly the kind of thing that must not be written down either.+ log.warn('telemetry: renderer sent a value the catalogue does not allow', {+ event: 'telemetry_renderer_rejected',+ telemetryEvent: request.name,+ reason: 'invalid_properties',+ });+ return;+ }++ const properties = parsed.data as TelemetryEventMap[RendererTelemetryEvent];+ if (!ONCE_PER_INSTALL.has(request.name)) {+ trackEvent(request.name, properties);+ return;+ }++ void claimOnce(request.name)+ .then((first) => {+ if (first) trackEvent(request.name, properties);+ })+ .catch(() => {+ // A record we cannot read is not a reason to report a second time: the+ // duplicate is the failure mode this exists to prevent.+ });+}diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/shape.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/shape.tsnew file mode 100644index 000000000..1cc0a470e--- /dev/null+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/shape.ts@@ -0,0 +1,15 @@+import { getLocationById } from '@main/core/locations/store';+import type { TelemetryLocationKind } from './events';++/**+ * Where a location runs.+ *+ * `unknown` is reported rather than guessed when the row has gone — a wrong+ * answer here is indistinguishable from a real one. Reads the database, which is+ * why the pure provider-id helper lives in `./agent-type` rather than here.+ */+export async function locationKindOf(locationId: string): Promise<TelemetryLocationKind> {+ const location = await getLocationById(locationId);+ if (!location) return 'unknown';+ return location.sshHost ? 'remote' : 'local';+}diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/telemetry-listeners.test.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/telemetry-listeners.test.tsindex aa195a5d5..1898ef260 100644--- a/console/apps/switch-console-desktop/src/main/core/telemetry/telemetry-listeners.test.ts+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/telemetry-listeners.test.ts@@ -57,9 +57,29 @@ function onLocation(kind: 'local' | 'remote' | 'missing') {function startSession(id: string, providerId = 'claude') {vi.mocked(getAgentById).mockResolvedValue({ id: 'agent', locationId: 'loc' } as never);- return emit('sessionService', 'session:created', { id, agentId: 'agent', providerId });+ return emit(+ 'sessionService',+ 'session:created',+ { id, agentId: 'agent', providerId },+ { id, agentId: 'agent', title: 'Session', entryPoint: 'sidebar' }+ );}+/**+ * What every session start reports beyond the two dimensions under test.+ *+ * The helper above declares no start source, and that is reported as `unknown`:+ * a caller that said nothing is not evidence a person was there.+ */+const SESSION_START_CONTEXT = {+ outcome: 'success',+ failure_reason: 'none',+ entry_point: 'sidebar',+ start_source: 'unknown',+ has_initial_prompt: false,+ connected_to_room: false,+} as const;+registerTelemetryListeners();beforeEach(() => {@@ -70,22 +90,28 @@ describe('agent_created', () => {it('reports where the agent runs', async () => {onLocation('remote');- await emit('agents', 'agent:created', { providerId: 'codex', locationId: 'loc' });+ await emit('agents', 'agent:created', { providerId: 'codex', locationId: 'loc' }, 'sidebar');expect(trackEvent).toHaveBeenCalledWith('agent_created', {agent_type: 'codex',location: 'remote',+ outcome: 'success',+ failure_reason: 'none',+ entry_point: 'sidebar',});});it('says unknown rather than guessing when the location has gone', async () => {onLocation('missing');- await emit('agents', 'agent:created', { providerId: 'codex', locationId: 'gone' });+ await emit('agents', 'agent:created', { providerId: 'codex', locationId: 'gone' }, 'sidebar');expect(trackEvent).toHaveBeenCalledWith('agent_created', {agent_type: 'codex',location: 'unknown',+ outcome: 'success',+ failure_reason: 'none',+ entry_point: 'sidebar',});});@@ -94,15 +120,52 @@ describe('agent_created', () => {// value would otherwise become free text in a payload.onLocation('local');- await emit('agents', 'agent:created', {- providerId: '/Users/someone/custom-agent',- locationId: 'loc',- });+ await emit(+ 'agents',+ 'agent:created',+ { providerId: '/Users/someone/custom-agent', locationId: 'loc' },+ 'sidebar'+ );expect(trackEvent).toHaveBeenCalledWith('agent_created', {agent_type: 'unknown',location: 'local',+ outcome: 'success',+ failure_reason: 'none',+ entry_point: 'sidebar',+ });+ });+});++describe('a session started in a room', () => {+ it('reports that a room was asked for, and who asked, never which room', async () => {+ onLocation('local');+ vi.mocked(getAgentById).mockResolvedValue({ id: 'agent', locationId: 'loc' } as never);++ await emit(+ 'sessionService',+ 'session:created',+ { id: 's-room', agentId: 'agent', providerId: 'claude' },+ {+ id: 's-room',+ agentId: 'agent',+ title: 'Session',+ entryPoint: 'sidebar',+ startSource: 'user',+ initialPrompt: 'connect to switch room alpha and audit the deploy',+ connectedToRoom: true,+ }+ );++ expect(trackEvent).toHaveBeenCalledWith('session_started', {+ ...SESSION_START_CONTEXT,+ agent_type: 'claude',+ location: 'local',+ start_source: 'user',+ has_initial_prompt: true,+ connected_to_room: true,});+ expect(JSON.stringify(vi.mocked(trackEvent).mock.calls)).not.toContain('alpha');});});@@ -113,6 +176,7 @@ describe('a session ending', () => {expect(trackEvent).toHaveBeenCalledWith('session_started', {agent_type: 'claude',location: 'local',+ ...SESSION_START_CONTEXT,});await emit('sessionService', 'session:archived', 's-normal');@@ -167,6 +231,28 @@ describe('a session ending', () => {expect(trackEvent).not.toHaveBeenCalled();});+ it('ends a second time once a restore has put it back into use', async () => {+ // The record of the first ending is there to collapse two endings moments+ // apart, not to retire a session id for the life of the run — an archived+ // session that is un-archived and later deleted has ended twice.+ onLocation('local');+ await startSession('s-unarchived');+ await emit('sessionService', 'session:archived', 's-unarchived');+ vi.mocked(trackEvent).mockClear();++ await emit('sessionService', 'session:restored', 's-unarchived');+ await emit('sessionService', 'session:deleted', 's-unarchived');++ // Unknown because a restore is the row coming back, not the session+ // running again: what it is gets re-learned when its runtime does.+ expect(trackEvent).toHaveBeenCalledTimes(1);+ expect(trackEvent).toHaveBeenCalledWith('session_ended', {+ agent_type: 'unknown',+ location: 'unknown',+ outcome: 'normal',+ });+ });+it('reports one pruned from its remote host, which arrives on the other bus', async () => {// The reconciler deletes the row itself when a session has gone from the// VM, or was terminated from another client. Subscribing only to thediff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/telemetry-listeners.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/telemetry-listeners.tsindex bb35da458..32901822e 100644--- a/console/apps/switch-console-desktop/src/main/core/telemetry/telemetry-listeners.ts+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/telemetry-listeners.ts@@ -1,14 +1,13 @@import { agentEvents } from '@main/core/agents/agent-events';import { getAgentById } from '@main/core/agents/getAgentById';-import { getLocationById } from '@main/core/locations/store';import { getSession } from '@main/core/sessions/operations/getSession';import { sessionHooks } from '@main/core/sessions/session-hooks';import { sessionService } from '@main/core/sessions/session-service';-import {- isValidProviderId,- type AgentProviderId,-} from '@shared/core/providers/agent-provider-registry';+import type { AgentProviderId } from '@shared/core/providers/agent-provider-registry';+import { agentTypeOf } from './agent-type';import type { TelemetryEventMap, TelemetryLocationKind } from './events';+import { entryPointOf, startSourceOf } from './narrow';+import { locationKindOf } from './shape';import { trackEvent } from './telemetry-service';type SessionShape = {@@ -38,17 +37,6 @@ const liveSessions = new Map<string, SessionShape>();*/const endedSessions = new Set<string>();-/** A provider id straight from the database is typed, not validated. */-function agentTypeOf(providerId: string): AgentProviderId | 'unknown' {- return isValidProviderId(providerId) ? providerId : 'unknown';-}--async function locationKindOf(locationId: string): Promise<TelemetryLocationKind> {- const location = await getLocationById(locationId);- if (!location) return 'unknown';- return location.sshHost ? 'remote' : 'local';-}-function rememberEnded(sessionId: string): void {endedSessions.add(sessionId);if (endedSessions.size <= ENDED_SESSION_MEMORY) return;@@ -109,14 +97,17 @@ async function rememberSession(sessionId: string, locationId: string): Promise<v* connector being installed — call `trackEvent` at their own site.*/export function registerTelemetryListeners(): void {- agentEvents.on('agent:created', async (agent) => {+ agentEvents.on('agent:created', async (agent, entryPoint) => {trackEvent('agent_created', {agent_type: agentTypeOf(agent.providerId),location: await locationKindOf(agent.locationId),+ outcome: 'success',+ failure_reason: 'none',+ entry_point: entryPointOf(entryPoint),});});- sessionService.on('session:created', async (session) => {+ sessionService.on('session:created', async (session, params) => {const agent = await getAgentById(session.agentId);const shape: SessionShape = {agent_type: agentTypeOf(session.providerId),@@ -130,7 +121,21 @@ export function registerTelemetryListeners(): void {if (endedSessions.has(session.id)) return;liveSessions.set(session.id, shape);- trackEvent('session_started', shape);+ trackEvent('session_started', {+ ...shape,+ outcome: 'success',+ failure_reason: 'none',+ entry_point: entryPointOf(params.entryPoint),+ start_source: startSourceOf(params.startSource),+ // The same test `createSession` itself applies, so the reported flag and+ // the prompt the session actually launched with cannot disagree.+ has_initial_prompt: (params.initialPrompt?.trim().length ?? 0) > 0,+ // Declared by whoever asked for the session. Not read back from the+ // poller: its record of the intended room is consumed during the launch,+ // before this hook runs, so asking here answers no for every session that+ // actually started.+ connected_to_room: params.connectedToRoom === true,+ });});sessionService.on('session:runtime-ready', async (sessionId, result) => {@@ -140,6 +145,14 @@ export function registerTelemetryListeners(): void {sessionService.on('session:deleted', (sessionId) => endSession(sessionId, 'normal'));sessionService.on('session:archived', (sessionId) => endSession(sessionId, 'normal'));+ // Un-archiving puts a session that has already reported an end back into use.+ // Forgetting that it ended is what lets it report the next one: the record is+ // there to collapse two endings moments apart, not to retire a session id for+ // the life of the run.+ sessionService.on('session:restored', (sessionId) => {+ endedSessions.delete(sessionId);+ });+// Rows deleted outside the sessionService path — the remote-session// reconciler pruning a session that has gone from its VM, or one terminated// from another client — arrive on the other bus. Subscribing to only onediff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/telemetry-service.test.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/telemetry-service.test.tsindex a2eb5999d..b8deb3485 100644--- a/console/apps/switch-console-desktop/src/main/core/telemetry/telemetry-service.test.ts+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/telemetry-service.test.ts@@ -82,7 +82,13 @@ describe('the consent gate', () => {it('sends once consent is given', async () => {vi.mocked(isTelemetryAllowed).mockResolvedValue(true);- await telemetryService.track('agent_created', { agent_type: 'codex', location: 'remote' });+ await telemetryService.track('agent_created', {+ agent_type: 'codex',+ location: 'remote',+ outcome: 'success',+ failure_reason: 'none',+ entry_point: 'sidebar',+ });expect(fetchMock).toHaveBeenCalledTimes(1);const [url] = fetchMock.mock.calls[0] as [string];@@ -130,6 +136,41 @@ describe('a build that cannot send', () => {});});+describe('asking in advance whether a send would arrive', () => {+ /**+ * The once-per-install events spend a record that is never given back, so they+ * ask before they claim. The answer has to be the same two refusals `track`+ * applies, or the question is worse than not asking.+ */+ it('is no when the build cannot send, without asking the user', async () => {+ delete process.env.SWITCHDASH_TELEMETRY_DEV;+ vi.mocked(isTelemetryAllowed).mockResolvedValue(true);++ expect(await telemetryService.canSend()).toBe(false);+ expect(isTelemetryAllowed).not.toHaveBeenCalled();+ });++ it('is no when the user has not agreed', async () => {+ vi.mocked(isTelemetryAllowed).mockResolvedValue(false);++ expect(await telemetryService.canSend()).toBe(false);+ });++ it('is yes when the build can send and the user has agreed', async () => {+ vi.mocked(isTelemetryAllowed).mockResolvedValue(true);++ expect(await telemetryService.canSend()).toBe(true);+ });++ it('answers without sending anything', async () => {+ vi.mocked(isTelemetryAllowed).mockResolvedValue(true);++ await telemetryService.canSend();++ expect(fetchMock).not.toHaveBeenCalled();+ });+});+describe('the payload', () => {beforeEach(() => {vi.mocked(isTelemetryAllowed).mockResolvedValue(true);@@ -138,7 +179,16 @@ describe('the payload', () => {it('identifies the install, and no user', async () => {// The relay reads this as Amplitude's device id. It sets a user id only// for a caller that sends one, which this is not.- await telemetryService.track('session_started', { agent_type: 'claude', location: 'local' });+ await telemetryService.track('session_started', {+ agent_type: 'claude',+ location: 'local',+ outcome: 'success',+ failure_reason: 'none',+ entry_point: 'sidebar',+ start_source: 'user',+ has_initial_prompt: false,+ connected_to_room: false,+ });expect(sentResource()['flint.client_id']).toBe('install-abc');expect(sentResource()).not.toHaveProperty('flint.user_id');diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/telemetry-service.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/telemetry-service.tsindex 14d9ef983..6ea614b54 100644--- a/console/apps/switch-console-desktop/src/main/core/telemetry/telemetry-service.ts+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/telemetry-service.ts@@ -54,6 +54,20 @@ class TelemetryService {await postTelemetryEvent(payload, resolution.config);}+ /**+ * Whether an event sent right now would actually go anywhere.+ *+ * The same two refusals `track` applies, asked in advance. Only the+ * once-per-install events need this: they spend a record that is never given+ * back, so spending it on a send that consent then discards would retire the+ * event for the life of the install. Nothing else should call it — everywhere+ * else, asking first and sending second is two reads of a gate that can change+ * in between, and `track` already reads it at the only moment that matters.+ */+ async canSend(): Promise<boolean> {+ return resolveTelemetryConfig().enabled && (await isTelemetryAllowed());+ }+private resolveVersion(): Promise<string> {this.appVersion ??= resolveAppVersion();return this.appVersion;diff --git a/console/apps/switch-console-desktop/src/main/core/updates/controller.ts b/console/apps/switch-console-desktop/src/main/core/updates/controller.tsindex 59b9a3a7c..08fb7b2b4 100644--- a/console/apps/switch-console-desktop/src/main/core/updates/controller.ts+++ b/console/apps/switch-console-desktop/src/main/core/updates/controller.ts@@ -1,13 +1,14 @@import { app, shell } from 'electron';+import type { TelemetryUpdateTrigger } from '@main/core/telemetry/events';import { updateService } from '@main/core/updates/update-service';import { createRPCController } from '@shared/lib/ipc/rpc';import { SWITCH_CONSOLE_RELEASES_URL } from '@shared/urls';import { formatUpdaterError } from './utils';export const updateController = createRPCController({- check: async () => {+ check: async (trigger: TelemetryUpdateTrigger = 'user') => {try {- const result = await updateService.checkForUpdates();+ const result = await updateService.checkForUpdates(trigger);return { success: true, result: result ?? null };} catch (error) {return { success: false, error: formatUpdaterError(error) };diff --git a/console/apps/switch-console-desktop/src/main/core/updates/pending-install.ts b/console/apps/switch-console-desktop/src/main/core/updates/pending-install.tsnew file mode 100644index 000000000..355b82cac--- /dev/null+++ b/console/apps/switch-console-desktop/src/main/core/updates/pending-install.ts@@ -0,0 +1,34 @@+import { KV } from '@main/db/kv';++/**+ * That an update was handed to the installer, remembered across the restart.+ *+ * An install that works ends this process, so the only way to report that one+ * happened is to write it down first and read it back in the process that comes+ * after. The marker is set immediately before the handover and cleared by the+ * rollback, so on the next launch its presence means the app really did go down+ * for an installer rather than unwinding back to "ready to install".+ *+ * It says only that a handover happened — not that the new version is running.+ * That question is answered by the version `app_launched` carries.+ */+const store = new KV<Record<string, boolean>>('updates:pending-install');++const KEY = 'handover';++export const pendingInstall = {+ set: (): Promise<void> => store.set(KEY, true),+ clear: (): Promise<void> => store.del(KEY),++ /**+ * Whether the previous run handed an update over, clearing the record so a+ * launch is only ever counted once. Cleared before the caller reports, so a+ * report that fails to send loses one event rather than repeating it on every+ * launch from here on.+ */+ async take(): Promise<boolean> {+ if ((await store.get(KEY)) !== true) return false;+ await store.del(KEY);+ return true;+ },+};diff --git a/console/apps/switch-console-desktop/src/main/core/updates/update-service.test.ts b/console/apps/switch-console-desktop/src/main/core/updates/update-service.test.tsnew file mode 100644index 000000000..b795ee9c8--- /dev/null+++ b/console/apps/switch-console-desktop/src/main/core/updates/update-service.test.ts@@ -0,0 +1,253 @@+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';++/**+ * What a check and an install attempt report.+ *+ * Both are answered from the updater's own results rather than from the call+ * returning: a check that finds nothing still comes back with a release+ * attached, and an install that fails does so minutes after the app handed over.+ */++const h = vi.hoisted(() => ({+ handlers: new Map<string, (arg?: unknown) => void>(),+ setFeedURL: vi.fn(),+ checkForUpdatesAndNotify: vi.fn(),+ downloadUpdate: vi.fn(),+ quitAndInstall: vi.fn(),+ trackEvent: vi.fn(),+ /** The handover marker, which outlives the process in the real thing. */+ pending: { handover: false },+}));++vi.mock('electron', async () => {+ const { EventEmitter } = await import('node:events');+ return { app: new EventEmitter() };+});++vi.mock('electron-updater', () => ({+ default: {+ autoUpdater: {+ on: (event: string, fn: (arg?: unknown) => void) => h.handlers.set(event, fn),+ setFeedURL: h.setFeedURL,+ checkForUpdatesAndNotify: h.checkForUpdatesAndNotify,+ downloadUpdate: h.downloadUpdate,+ quitAndInstall: h.quitAndInstall,+ },+ },+}));++vi.mock('@main/core/telemetry/telemetry-service', () => ({ trackEvent: h.trackEvent }));+// Backed by the database in the real thing, which this project has no Electron+// app to open.+vi.mock('./pending-install', () => ({+ pendingInstall: {+ set: async () => {+ h.pending.handover = true;+ },+ clear: async () => {+ h.pending.handover = false;+ },+ take: async () => {+ const held = h.pending.handover;+ h.pending.handover = false;+ return held;+ },+ },+}));+vi.mock('@main/core/app/utils', () => ({ resolveAppVersion: async () => '1.2.3' }));+vi.mock('@main/lib/events', () => ({ events: { emit: vi.fn() } }));+vi.mock('@main/lib/logger', () => ({+ log: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },+}));++import type { EventEmitter } from 'node:events';+import { app } from 'electron';+import { updateService } from './update-service';++/** The app going down for the installer, as the service observes it. */+function quitApp(): void {+ (app as unknown as EventEmitter).emit('before-quit');+}++function installEvents(): unknown[] {+ return h.trackEvent.mock.calls.filter(([name]) => name === 'update_install_started');+}++beforeAll(async () => {+ vi.useFakeTimers();+ // The updater is inert outside a packaged build, and the dev harness is the+ // path that stands in for it there — so the real one has to be asked for.+ vi.stubEnv('DEV', false);+ await updateService.initialize();+ // Drop the startup check it schedules; every test here drives its own.+ updateService.dispose();+});++afterAll(() => {+ vi.useRealTimers();+ vi.unstubAllEnvs();+});++beforeEach(() => {+ h.trackEvent.mockClear();+});++describe('what a check reports', () => {+ it('reports a check that found nothing as up to date', async () => {+ // The updater answers its not-available branch with the release it just+ // compared this build against, so an `updateInfo` is present either way.+ h.checkForUpdatesAndNotify.mockResolvedValue({+ isUpdateAvailable: false,+ versionInfo: { version: '1.2.3' },+ updateInfo: { version: '1.2.3' },+ });++ await expect(updateService.checkForUpdates('scheduled')).resolves.toBeNull();++ expect(h.trackEvent).toHaveBeenCalledWith('update_checked', {+ trigger: 'scheduled',+ result: 'up_to_date',+ });+ });++ it('reports a check that found one as available', async () => {+ h.checkForUpdatesAndNotify.mockResolvedValue({+ isUpdateAvailable: true,+ versionInfo: { version: '1.3.0' },+ updateInfo: { version: '1.3.0' },+ });++ await expect(updateService.checkForUpdates('user')).resolves.toMatchObject({+ version: '1.3.0',+ });++ expect(h.trackEvent).toHaveBeenCalledWith('update_checked', {+ trigger: 'user',+ result: 'available',+ });+ });++ it('reports a check that could not run as failed', async () => {+ h.checkForUpdatesAndNotify.mockRejectedValue(new Error('HTTP 503'));++ await expect(updateService.checkForUpdates('startup')).rejects.toThrow();++ expect(h.trackEvent).toHaveBeenCalledWith('update_checked', {+ trigger: 'startup',+ result: 'failed',+ });+ });+});++describe('what one install attempt reports', () => {+ beforeEach(() => {+ // Through the service's own listeners: "downloaded" is not reachable any+ // other way, and going round them would test a state the app cannot be in.+ h.handlers.get('update-available')?.({ version: '1.3.0' });+ h.handlers.get('update-downloaded')?.({ version: '1.3.0' });+ h.quitAndInstall.mockReset();+ h.trackEvent.mockClear();+ });++ afterEach(() => {+ // Unwind an attempt that is still open, so the next test is not refused as a+ // duplicate. The latch means this adds nothing to what was already reported.+ vi.advanceTimersByTime(3 * 60 * 1000);+ });++ it('says nothing about a handover from inside the process it ends', () => {+ updateService.quitAndInstall();+ vi.advanceTimersByTime(250);+ quitApp();++ // The shutdown handler calls `app.exit`, and a send is a consent read and an+ // HTTP post — neither survives it. What the handover leaves behind is the+ // marker, which the next launch reports from.+ expect(h.quitAndInstall).toHaveBeenCalled();+ expect(installEvents()).toEqual([]);+ expect(h.pending.handover).toBe(true);+ });++ it('reports a handover that threw, and reports only that', () => {+ h.quitAndInstall.mockImplementation(() => {+ throw new Error('installer is missing');+ });++ updateService.quitAndInstall();+ vi.advanceTimersByTime(250);++ expect(installEvents()).toEqual([['update_install_started', { outcome: 'failure' }]]);+ });++ it('reports an install that never left as one failure', () => {+ updateService.quitAndInstall();+ vi.advanceTimersByTime(250);+ vi.advanceTimersByTime(2 * 60 * 1000);++ expect(installEvents()).toEqual([['update_install_started', { outcome: 'failure' }]]);+ });++ it('adds nothing when the app quits long after an attempt was written off', () => {+ updateService.quitAndInstall();+ vi.advanceTimersByTime(250);+ vi.advanceTimersByTime(2 * 60 * 1000);+ quitApp();++ expect(installEvents()).toEqual([['update_install_started', { outcome: 'failure' }]]);+ // An attempt that unwound leaves nothing for the next launch to find, or it+ // would be reported as a success as well as a failure.+ expect(h.pending.handover).toBe(false);+ });+});++describe('the launch after an install', () => {+ beforeEach(() => {+ vi.resetModules();+ h.trackEvent.mockClear();+ });++ it('reports the handover the previous run wrote down', async () => {+ h.pending.handover = true;+ const { updateService: restarted } = await import('./update-service');+ await restarted.initialize();++ expect(installEvents()).toEqual([['update_install_started', { outcome: 'success' }]]);+ // Taken, not just read: a launch is counted once, and a user who never+ // updates again does not report this install on every start from here on.+ expect(h.pending.handover).toBe(false);+ });++ it('reports nothing on an ordinary launch', async () => {+ h.pending.handover = false;+ const { updateService: restarted } = await import('./update-service');+ await restarted.initialize();++ expect(installEvents()).toEqual([]);+ });+});++describe('the dev harness', () => {+ it('reports one event for a simulated install, not two', async () => {+ // A dev build has no binary to restart into, so the harness always unwinds.+ // That is one attempt and one outcome, the same as any other.+ vi.resetModules();+ vi.stubEnv('DEV', true);+ vi.stubEnv('SWITCHDASH_FAKE_UPDATE', 'available');+ vi.stubEnv('SWITCHDASH_FAKE_UPDATE_MS', '100');++ const { updateService: harnessed } = await import('./update-service');+ await harnessed.initialize();++ await vi.advanceTimersByTimeAsync(3_000);+ const download = harnessed.downloadUpdate();+ await vi.advanceTimersByTimeAsync(3_000);+ await download;++ h.trackEvent.mockClear();+ harnessed.quitAndInstall();+ await vi.advanceTimersByTimeAsync(5_000);++ expect(installEvents()).toEqual([['update_install_started', { outcome: 'failure' }]]);+ harnessed.dispose();+ });+});diff --git a/console/apps/switch-console-desktop/src/main/core/updates/update-service.ts b/console/apps/switch-console-desktop/src/main/core/updates/update-service.tsindex df2d96c1b..e28b18823 100644--- a/console/apps/switch-console-desktop/src/main/core/updates/update-service.ts+++ b/console/apps/switch-console-desktop/src/main/core/updates/update-service.ts@@ -5,6 +5,9 @@ import _electronUpdater, {type Logger as UpdaterLogger,} from 'electron-updater';import { resolveAppVersion } from '@main/core/app/utils';+import type { TelemetryUpdateTrigger } from '@main/core/telemetry/events';+import { updateTriggerOf } from '@main/core/telemetry/narrow';+import { trackEvent } from '@main/core/telemetry/telemetry-service';import { events } from '@main/lib/events';import { log } from '@main/lib/logger';import {@@ -32,6 +35,7 @@ import {readFakeDownloadDuration,readFakeUpdateScenario,} from './dev-harness';+import { pendingInstall } from './pending-install';import { formatUpdaterError, sanitizeUpdaterLogArgs } from './utils';const { autoUpdater } = _electronUpdater;@@ -87,6 +91,13 @@ class UpdateService implements IInitializable, IDisposable {this.updateState.currentVersion = await resolveAppVersion();+ // Before the dev-harness branch and before `active`: the install this+ // reports belonged to the run that ended, and whether this one can check+ // for updates has no bearing on it.+ if (await pendingInstall.take()) {+ trackEvent('update_install_started', { outcome: 'success' });+ }+if (import.meta.env.DEV) {this.setupDevHarness();return;@@ -236,20 +247,39 @@ class UpdateService implements IInitializable, IDisposable {}this.updateState.nextCheck = new Date(Date.now() + delay);this.checkTimer = setTimeout(() => {- this.checkForUpdates().catch((e) => {+ this.checkForUpdates('scheduled').catch((e) => {log.error('Scheduled update check failed:', e);});}, delay);}- async checkForUpdates(): Promise<UpdateInfo | null> {+ /**+ * Check for an update.+ *+ * `trigger` says who asked. A check that arrives while one is already running+ * joins it rather than starting a second, so it is reported under the trigger+ * of the check that actually ran — the alternative is counting one check twice.+ */+ async checkForUpdates(trigger: TelemetryUpdateTrigger = 'user'): Promise<UpdateInfo | null> {if (!this.active) return null;if (this.currentCheckPromise) return this.currentCheckPromise;- this.currentCheckPromise = this._performCheck().finally(() => {- this.currentCheckPromise = null;- this.scheduleNextCheck();- });+ this.currentCheckPromise = this._performCheck()+ .then((info) => {+ trackEvent('update_checked', {+ trigger: updateTriggerOf(trigger),+ result: info ? 'available' : 'up_to_date',+ });+ return info;+ })+ .catch((error: unknown) => {+ trackEvent('update_checked', { trigger: updateTriggerOf(trigger), result: 'failed' });+ throw error;+ })+ .finally(() => {+ this.currentCheckPromise = null;+ this.scheduleNextCheck();+ });return this.currentCheckPromise;}@@ -274,7 +304,11 @@ class UpdateService implements IInitializable, IDisposable {});const result = await autoUpdater.checkForUpdatesAndNotify();- return result?.updateInfo ?? null;+ // Both branches of the updater's check carry an `updateInfo`: the+ // not-available one returns the release it just compared this build against.+ // `isUpdateAvailable` is the field that separates them, and null here is what+ // every caller reads as "nothing to install".+ return result?.isUpdateAvailable ? result.updateInfo : null;}async downloadUpdate(): Promise<void> {@@ -297,7 +331,9 @@ class UpdateService implements IInitializable, IDisposable {try {if (this.fake) await this.fake.download();else await autoUpdater.downloadUpdate();+ trackEvent('update_downloaded', { outcome: 'success' });} catch (error: unknown) {+ trackEvent('update_downloaded', { outcome: 'failure' });const errorMessage = formatUpdaterError(error);log.error('Update download failed:', errorMessage, error);@@ -336,15 +372,14 @@ class UpdateService implements IInitializable, IDisposable {toVersion: this.updateState.availableVersion,});- const clearGuard = () => {- if (this.installRestartGuardTimer) {- clearTimeout(this.installRestartGuardTimer);- this.installRestartGuardTimer = undefined;- }- };-+ // One attempt, one event. Only one of the two outcomes can happen — the app+ // goes down for the installer, or it is still here afterwards — and the+ // latch is what keeps a handover that later unwinds from being counted in+ // both directions.const rollback = (reason: string) => {clearGuard();+ void pendingInstall.clear();+ trackEvent('update_install_started', { outcome: 'failure' });this.installRequested = false;this.updateState.status = 'downloaded';if (this.updateState.availableVersion) {@@ -353,6 +388,13 @@ class UpdateService implements IInitializable, IDisposable {log.error(reason);};+ const clearGuard = () => {+ if (this.installRestartGuardTimer) {+ clearTimeout(this.installRestartGuardTimer);+ this.installRestartGuardTimer = undefined;+ }+ };+if (this.fake) {// A dev build has no new binary to restart into. Unwind quickly so the// "ready to install" state is reachable again instead of stranding the UI@@ -363,6 +405,16 @@ class UpdateService implements IInitializable, IDisposable {return;}+ // Written before handing over, and read on the next launch. A successful+ // install takes the process down with it, so there is no moment inside this+ // one at which success can be sent: `before-quit` runs after the shutdown+ // handler that calls `app.exit`, and even first in the queue it would be+ // racing a consent read and an HTTP post against the process ending. A+ // record that survives the restart is the only version of this that is not+ // a guess, and the marker's absence is what `rollback` uses to say the+ // handover did not take.+ void pendingInstall.set();+this.installRestartGuardTimer = setTimeout(() => {rollback('quitAndInstall timed out before app quit; allowing retry');}, INSTALL_RESTART_GUARD_TIMEOUT_MS);diff --git a/console/apps/switch-console-desktop/src/main/rpc.ts b/console/apps/switch-console-desktop/src/main/rpc.tsindex 773a49bb3..84e297228 100644--- a/console/apps/switch-console-desktop/src/main/rpc.ts+++ b/console/apps/switch-console-desktop/src/main/rpc.ts@@ -19,6 +19,7 @@ import { sidecarController } from './core/sidecar/controller';import { switchRoomsController } from './core/switch-rooms/controller';import { switchServersController } from './core/switch-servers/controller';import { switchSetupController } from './core/switch-setup/controller';+import { telemetryController } from './core/telemetry/controller';import { updateController } from './core/updates/controller';import { viewStateController } from './core/view-state/controller';@@ -44,6 +45,7 @@ export const rpcRouter = createRPCRouter({remoteSwitchServer: remoteSwitchServerController,remoteHosts: remoteHostsController,sidecar: sidecarController,+ telemetry: telemetryController,fs: createRPCNamespace({watch: filesController,}),diff --git a/console/apps/switch-console-desktop/src/renderer/app/home-view.tsx b/console/apps/switch-console-desktop/src/renderer/app/home-view.tsxindex 893757267..b686c0028 100644--- a/console/apps/switch-console-desktop/src/renderer/app/home-view.tsx+++ b/console/apps/switch-console-desktop/src/renderer/app/home-view.tsx@@ -22,12 +22,8 @@ const TAGLINE = 'A platform-agnostic framework to bring humans and agents togeth* from Settings → General.*/export const HomeMainPanel = observer(function HomeMainPanel() {- const { steps, complete, startStep } = useOnboardingChecklist();- const {- value: onboarding,- update: updateOnboarding,- isLoading,- } = useAppSettingsKey('onboarding');+ const { steps, complete, startStep, dismiss: dismissChecklist } = useOnboardingChecklist();+ const { value: onboarding, isLoading } = useAppSettingsKey('onboarding');// Until the setting has loaded there is no honest answer, and guessing "show"// flashes the checklist at someone who dismissed it launches ago.const showChecklist = !isLoading && onboarding?.showChecklist === true;@@ -54,7 +50,7 @@ export const HomeMainPanel = observer(function HomeMainPanel() {steps={steps}complete={complete}onStart={startStep}- onDismiss={() => updateOnboarding({ showChecklist: false })}+ onDismiss={dismissChecklist}/>)}<WelcomeLearnMore />diff --git a/console/apps/switch-console-desktop/src/renderer/app/view-registry.ts b/console/apps/switch-console-desktop/src/renderer/app/view-registry.tsindex eeff5f35d..d4536aa00 100644--- a/console/apps/switch-console-desktop/src/renderer/app/view-registry.ts+++ b/console/apps/switch-console-desktop/src/renderer/app/view-registry.ts@@ -11,6 +11,7 @@ import { serverRoomsView } from '@renderer/features/switch-servers/server-rooms-import { serverView } from '@renderer/features/switch-servers/view';import type { CommandProvider } from '@renderer/lib/commands/types';import { appState } from '@renderer/lib/stores/app-state';+import type { ViewIdName } from '@shared/core/views/view-ids';// Switch Console views: agents-at-a-location (location), sessions (session), home, settings,// and a connected Switch gateway's workspace — its Home (server) plus that@@ -53,6 +54,19 @@ type Views = typeof views;export type ViewId = keyof Views;+/**+ * The registry and the shared list of view ids say the same thing.+ *+ * The list is what the main process reports against, and it cannot import this+ * file. Both directions are asserted, so adding a view without naming it there —+ * or leaving a name behind after removing one — fails to compile instead of+ * quietly reporting a screen that does not exist or missing one that does.+ */+const _viewIdsAreExhaustive: ViewIdName extends ViewId ? true : never = true;+const _viewIdsAreComplete: ViewId extends ViewIdName ? true : never = true;+void _viewIdsAreExhaustive;+void _viewIdsAreComplete;+export type WrapParams<TId extends ViewId> = Views[TId] extends {WrapView: ComponentType<infer P>;}diff --git a/console/apps/switch-console-desktop/src/renderer/features/command-palette/command-palette-modal.tsx b/console/apps/switch-console-desktop/src/renderer/features/command-palette/command-palette-modal.tsxindex 231f44be6..90538ac04 100644--- a/console/apps/switch-console-desktop/src/renderer/features/command-palette/command-palette-modal.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/command-palette/command-palette-modal.tsx@@ -19,9 +19,11 @@ import { useNavigate } from '@renderer/lib/layout/navigation-provider';import { scopeToLocationServer } from '@renderer/lib/layout/scope-to-server';import { type BaseModalProps } from '@renderer/lib/modal/modal-provider';import { appState, sidebarStore } from '@renderer/lib/stores/app-state';+import { report } from '@renderer/lib/telemetry/report';import { Shortcut } from '@renderer/lib/ui/shortcut';import { cn } from '@renderer/utils/utils';import { ALL_COMMAND_DEFS, type CommandDef } from '@shared/commands';+import type { CommandId } from '@shared/commands';import type { SearchItem, SearchResult } from '@shared/core/search';import { getCommandIcon } from './command-icons';import { PaletteAgentItem } from './palette-agent-item';@@ -234,6 +236,7 @@ export function CommandPaletteModal({icon: getCommandIcon(def?.iconKey),execute: () => {handleClose();+ report('command_executed', { command_id: cmd.id as CommandId, invoked_by: 'palette' });cmd.execute();},};@@ -317,6 +320,7 @@ export function CommandPaletteModal({icon: getCommandIcon(def?.iconKey),execute: () => {handleClose();+ report('command_executed', { command_id: live.id as CommandId, invoked_by: 'palette' });live.execute();},};@@ -504,6 +508,10 @@ export function CommandPaletteModal({item={item}onSelect={() => {handleClose();+ report('command_executed', {+ command_id: live.id as CommandId,+ invoked_by: 'palette',+ });live.execute();}}/>diff --git a/console/apps/switch-console-desktop/src/renderer/features/locations/components/add-agent-modal/add-agent-modal.tsx b/console/apps/switch-console-desktop/src/renderer/features/locations/components/add-agent-modal/add-agent-modal.tsxindex 3dfd151aa..4624e5204 100644--- a/console/apps/switch-console-desktop/src/renderer/features/locations/components/add-agent-modal/add-agent-modal.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/locations/components/add-agent-modal/add-agent-modal.tsx@@ -43,6 +43,7 @@ import {import { log } from '@renderer/utils/logger';import type { AgentProviderConfig } from '@shared/core/agents/agent-provider-config';import { type ProvisionAgentResult } from '@shared/core/switch-servers/switch-servers';+import type { UiEntryPoint } from '@shared/core/telemetry/reporting';import { AgentAdvancedConfig } from './agent-advanced-config';import { AgentTypePicker } from './agent-type-picker';import { AgentIdentityFields, AgentSettingsSection } from './configure-agent-panel';@@ -54,7 +55,14 @@ import { useConfigureAgentForm, usePickMode } from './modes';// switch-connector `configure` skill has set up (its `.claude/settings.local.json`// carries the SWITCH_* env block). The richer Switch Console flows — SSH, clone, create// new GitHub repo — are out of scope for v0, so this modal is local + pick only.-export type AddLocationModalProps = BaseModalProps<void>;+export type AddLocationModalProps = BaseModalProps<void> & {+ /**+ * Which control opened this dialog. Required rather than defaulted: four+ * places open it, and a default would silently file whichever one forgot+ * under the same heading as the ones that did not.+ */+ entryPoint: UiEntryPoint;+};/** Sentinel `runHost` value meaning "run on this machine" (no remote host). */const LOCAL_RUN_LOCATION = 'local';@@ -68,7 +76,10 @@ function canonicalDir(dir: string): string {return stripped || (trimmed.startsWith('/') ? '/' : '');}-export const AddAgentModal = observer(function AddAgentModal({ onClose }: AddLocationModalProps) {+export const AddAgentModal = observer(function AddAgentModal({+ onClose,+ entryPoint,+}: AddLocationModalProps) {const [submitState, setSubmitState] = useState<'idle' | 'creating'>('idle');const { navigate } = useNavigate();const { setCloseGuard } = useModalContext();@@ -291,6 +302,7 @@ export const AddAgentModal = observer(function AddAgentModal({ onClose }: AddLocautoApprove: form.autoApprove,definitionAttributes: advancedAttributesRef.current,providerConfig: launchProfileConfigRef.current,+ entryPoint,});if (result.kind !== 'created') {reportProvisionError(result);diff --git a/console/apps/switch-console-desktop/src/renderer/features/locations/components/main-panel/agent-page-header.tsx b/console/apps/switch-console-desktop/src/renderer/features/locations/components/main-panel/agent-page-header.tsxindex abe4197e0..50a9ed1fb 100644--- a/console/apps/switch-console-desktop/src/renderer/features/locations/components/main-panel/agent-page-header.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/locations/components/main-panel/agent-page-header.tsx@@ -96,7 +96,11 @@ export const AgentPageHeader = observer(function AgentPageHeader() {</div>{description && <p className="text-sm text-foreground-muted">{description}</p>}<div className="mt-2 flex flex-wrap items-center gap-2">- <Button onClick={() => showCreateSessionModal({ locationId, agentName })}>+ <Button+ onClick={() =>+ showCreateSessionModal({ locationId, agentName, entryPoint: 'agent_page' })+ }+ >New Session <BoundShortcut settingsKey="newSession" /></Button>{roomable && (diff --git a/console/apps/switch-console-desktop/src/renderer/features/locations/components/session-view/session-list.tsx b/console/apps/switch-console-desktop/src/renderer/features/locations/components/session-view/session-list.tsxindex c967af2ce..8626db8ff 100644--- a/console/apps/switch-console-desktop/src/renderer/features/locations/components/session-view/session-list.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/locations/components/session-view/session-list.tsx@@ -152,7 +152,9 @@ export const SessionList = observer(function SessionList() {variant="ghost"size="icon-xs"aria-label="New session"- onClick={() => showCreateSessionModal({ locationId, agentName })}+ onClick={() =>+ showCreateSessionModal({ locationId, agentName, entryPoint: 'session_list' })+ }><Plus className="size-4" /></Button>diff --git a/console/apps/switch-console-desktop/src/renderer/features/locations/components/session-view/session-row.tsx b/console/apps/switch-console-desktop/src/renderer/features/locations/components/session-view/session-row.tsxindex 20b86e3e8..23d84a9b1 100644--- a/console/apps/switch-console-desktop/src/renderer/features/locations/components/session-view/session-row.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/locations/components/session-view/session-row.tsx@@ -35,7 +35,7 @@ export const SessionRow = observer(function SessionRow({const handleArchive = () => void sessionManager?.archiveSession(session.data.id);const handleRestore = () => void sessionManager?.restoreSession(session.data.id);- const handleProvision = () => void sessionManager?.provisionSession(session.data.id);+ const handleProvision = () => void sessionManager?.provisionSession(session.data.id, 'auto');const handleDelete = () =>showDeleteSession({locationId: session.locationId,diff --git a/console/apps/switch-console-desktop/src/renderer/features/locations/stores/location-manager.test.ts b/console/apps/switch-console-desktop/src/renderer/features/locations/stores/location-manager.test.tsindex 4a0801d62..ca400bed0 100644--- a/console/apps/switch-console-desktop/src/renderer/features/locations/stores/location-manager.test.ts+++ b/console/apps/switch-console-desktop/src/renderer/features/locations/stores/location-manager.test.ts@@ -233,7 +233,11 @@ describe('LocationManagerStore removeAgent', () => {await store.removeAgent('loc', 'a', { deleteInSwitch: false });- expect(mocks.deleteAgent).toHaveBeenCalledWith({ agentId: 'a', deleteInSwitch: false });+ expect(mocks.deleteAgent).toHaveBeenCalledWith({+ agentId: 'a',+ deleteInSwitch: false,+ trigger: 'user',+ });expect(store.locations.has('loc')).toBe(true);expect(agentsStore.byLocation.get('loc')?.map((x) => x.id)).toEqual(['b']);});@@ -248,7 +252,11 @@ describe('LocationManagerStore removeAgent', () => {await store.removeAgent('loc', 'a', { deleteInSwitch: true });- expect(mocks.deleteAgent).toHaveBeenCalledWith({ agentId: 'a', deleteInSwitch: true });+ expect(mocks.deleteAgent).toHaveBeenCalledWith({+ agentId: 'a',+ deleteInSwitch: true,+ trigger: 'user',+ });expect(store.locations.has('loc')).toBe(false);expect(agentsStore.byLocation.has('loc')).toBe(false);});diff --git a/console/apps/switch-console-desktop/src/renderer/features/locations/stores/location-manager.ts b/console/apps/switch-console-desktop/src/renderer/features/locations/stores/location-manager.tsindex d8693138a..27de5a71f 100644--- a/console/apps/switch-console-desktop/src/renderer/features/locations/stores/location-manager.ts+++ b/console/apps/switch-console-desktop/src/renderer/features/locations/stores/location-manager.ts@@ -256,7 +256,7 @@ export class LocationManagerStore {? navParams.sessionId: undefined;if (navSessionId) {- sessionManager.provisionSession(navSessionId).catch(() => {});+ sessionManager.provisionSession(navSessionId, 'auto').catch(() => {});}}})@@ -293,7 +293,13 @@ export class LocationManagerStore {appState.navigation.revalidate();try {await Promise.all(- agents.map((agent) => rpc.agents.deleteAgent({ agentId: agent.id, deleteInSwitch: false }))+ agents.map((agent) =>+ rpc.agents.deleteAgent({+ agentId: agent.id,+ deleteInSwitch: false,+ trigger: 'user',+ })+ ));} catch (error) {runInAction(() => {@@ -332,7 +338,11 @@ export class LocationManagerStore {if (remaining.length === 0) appState.navigation.revalidate();try {- await rpc.agents.deleteAgent({ agentId, deleteInSwitch: options.deleteInSwitch });+ await rpc.agents.deleteAgent({+ agentId,+ deleteInSwitch: options.deleteInSwitch,+ trigger: 'user',+ });// Reconcile against the source of truth (also corrects the optimistic guess).await agentsStore.load();} catch (error) {diff --git a/console/apps/switch-console-desktop/src/renderer/features/onboarding/sidebar-onboarding-checklist.tsx b/console/apps/switch-console-desktop/src/renderer/features/onboarding/sidebar-onboarding-checklist.tsxindex 129746573..7ce4df408 100644--- a/console/apps/switch-console-desktop/src/renderer/features/onboarding/sidebar-onboarding-checklist.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/onboarding/sidebar-onboarding-checklist.tsx@@ -13,8 +13,8 @@ import { useOnboardingChecklist } from './use-onboarding-checklist';* turn green is the point of having it).*/export const SidebarOnboardingChecklist = observer(function SidebarOnboardingChecklist() {- const { value, update, isLoading } = useAppSettingsKey('onboarding');- const { steps, complete, startStep } = useOnboardingChecklist();+ const { value, isLoading } = useAppSettingsKey('onboarding');+ const { steps, complete, startStep, dismiss } = useOnboardingChecklist();// Render nothing until the setting is known, rather than flashing a checklist// at someone who dismissed it three launches ago.@@ -27,7 +27,7 @@ export const SidebarOnboardingChecklist = observer(function SidebarOnboardingChecollapsed={appState.sidebar.onboardingChecklistCollapsed}onStart={startStep}onToggleCollapsed={() => appState.sidebar.toggleOnboardingChecklistCollapsed()}- onDismiss={() => update({ showChecklist: false })}+ onDismiss={dismiss}/>);});diff --git a/console/apps/switch-console-desktop/src/renderer/features/onboarding/use-onboarding-checklist.ts b/console/apps/switch-console-desktop/src/renderer/features/onboarding/use-onboarding-checklist.tsindex 8cdb74478..6fcc86ae9 100644--- a/console/apps/switch-console-desktop/src/renderer/features/onboarding/use-onboarding-checklist.ts+++ b/console/apps/switch-console-desktop/src/renderer/features/onboarding/use-onboarding-checklist.ts@@ -1,10 +1,13 @@-import { useCallback } from 'react';+import { useCallback, useEffect } from 'react';+import { useAppSettingsKey } from '@renderer/features/settings/use-app-settings-key';import { switchRoomsStore } from '@renderer/features/switch-servers/switch-rooms-store';import { switchServersStore } from '@renderer/features/switch-servers/switch-servers-store';+import { rpc } from '@renderer/lib/ipc';import { useNavigate } from '@renderer/lib/layout/navigation-provider';import { useShowModal } from '@renderer/lib/modal/modal-provider';import { appState } from '@renderer/lib/stores/app-state';import { useAgentTypeAvailability } from '@renderer/lib/stores/use-switch-setup';+import { report } from '@renderer/lib/telemetry/report';import {deriveOnboardingSteps,isOnboardingComplete,@@ -40,6 +43,8 @@ export type OnboardingChecklist = {complete: boolean;/** Opens whatever that step asks for — a dialog, or the settings tab. */startStep: (id: OnboardingStepId) => void;+ /** Hide the checklist. Routed through here so both dismiss buttons agree. */+ dismiss: () => void;};/**@@ -49,6 +54,7 @@ export type OnboardingChecklist = {*/export function useOnboardingChecklist(): OnboardingChecklist {const progress = useOnboardingProgress();+ const { value: onboarding } = useAppSettingsKey('onboarding');const showAddServerModal = useShowModal('addServerModal');const showAddAgentModal = useShowModal('addAgentModal');const showCreateRoomModal = useShowModal('createRoomModal');@@ -56,6 +62,7 @@ export function useOnboardingChecklist(): OnboardingChecklist {const startStep = useCallback((id: OnboardingStepId) => {+ report('onboarding_step_started', { step_id: id });switch (id) {case 'addServer':showAddServerModal({});@@ -64,7 +71,7 @@ export function useOnboardingChecklist(): OnboardingChecklist {navigate('settings', { tab: 'clis-models' });return;case 'onboardAgents':- showAddAgentModal({});+ showAddAgentModal({ entryPoint: 'onboarding' });return;case 'createRoom':showCreateRoomModal({});@@ -74,9 +81,27 @@ export function useOnboardingChecklist(): OnboardingChecklist {[showAddServerModal, showAddAgentModal, showCreateRoomModal, navigate]);+ const complete = isOnboardingComplete(progress);++ const dismiss = useCallback(() => {+ if (!onboarding) return;+ report('onboarding_checklist_dismissed', {});+ void rpc.appSettings.update('onboarding', { ...onboarding, showChecklist: false });+ }, [onboarding]);++ // Completion is a condition, not an event: it becomes true during a render and+ // is true again on every later launch. Asking more than once is harmless —+ // the main process keeps the record of whether it has already been reported,+ // because that record is our bookkeeping and not one of the user's settings.+ useEffect(() => {+ if (!complete) return;+ report('onboarding_completed', {});+ }, [complete]);+return {steps: deriveOnboardingSteps(progress),- complete: isOnboardingComplete(progress),+ complete,+ dismiss,startStep,};}diff --git a/console/apps/switch-console-desktop/src/renderer/features/remote-hosts/add-host-modal.tsx b/console/apps/switch-console-desktop/src/renderer/features/remote-hosts/add-host-modal.tsxindex 52cbf54f0..f2d90f4e8 100644--- a/console/apps/switch-console-desktop/src/renderer/features/remote-hosts/add-host-modal.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/remote-hosts/add-host-modal.tsx@@ -62,13 +62,24 @@ export function AddHostModal({ onboarded, onAdded, onClose }: AddHostModalProps)[configHosts.data, onboarded]);- const chooseHost = (alias: string) => {+ // Which affordance supplied the alias. Both write the same field, so without+ // recording it here nothing downstream can tell a host the app offered from+ // one someone had to already know the name of.+ const [pickedFromConfig, setPickedFromConfig] = useState(false);++ const chooseHost = (alias: string, fromConfig: boolean) => {setSshHost(alias);+ setPickedFromConfig(fromConfig);if (!nameEdited) setName(suggestName(alias));};const mutation = useMutation({- mutationFn: () => rpc.remoteHosts.onboardHost({ sshHost: sshHost.trim(), name: name.trim() }),+ mutationFn: () =>+ rpc.remoteHosts.onboardHost({+ sshHost: sshHost.trim(),+ name: name.trim(),+ pickedFromSshConfig: pickedFromConfig,+ }),onError: (error) => log.error('Failed to onboard remote host', { sshHost, error }),onSuccess: (host) => {onAdded(host.sshHost);@@ -102,7 +113,7 @@ export function AddHostModal({ onboarded, onAdded, onClose }: AddHostModalProps)<Spinner /> Reading ~/.ssh/config…</div>) : available.length > 0 ? (- <Select value={sshHost} onValueChange={(value) => chooseHost(value ?? '')}>+ <Select value={sshHost} onValueChange={(value) => chooseHost(value ?? '', true)}><SelectTrigger><SelectValue placeholder="Select a host alias" /></SelectTrigger>@@ -119,7 +130,7 @@ export function AddHostModal({ onboarded, onAdded, onClose }: AddHostModalProps)<Inputvalue={sshHost}placeholder="dev-vm"- onChange={(event) => chooseHost(event.target.value)}+ onChange={(event) => chooseHost(event.target.value, false)}/><p className="text-xs text-foreground-muted">{(configHosts.data ?? []).length === 0diff --git a/console/apps/switch-console-desktop/src/renderer/features/sessions/create-session-modal/create-session-modal.tsx b/console/apps/switch-console-desktop/src/renderer/features/sessions/create-session-modal/create-session-modal.tsxindex c28949802..57e08c5c8 100644--- a/console/apps/switch-console-desktop/src/renderer/features/sessions/create-session-modal/create-session-modal.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/sessions/create-session-modal/create-session-modal.tsx@@ -41,6 +41,7 @@ import { log } from '@renderer/utils/logger';import { cn } from '@renderer/utils/utils';import type { Agent } from '@shared/core/agents/agents';import type { RemoteAgentRoom } from '@shared/core/switch-servers/switch-servers';+import type { UiEntryPoint } from '@shared/core/telemetry/reporting';import { buildConnectPrompt } from './build-connect-prompt';// In Switch Console a "session" is a *session*: a `claude` process spawned in the agent's@@ -131,8 +132,15 @@ export const CreateSessionModal = observer(function CreateSessionModal({locationId,agentName,roomId,+ entryPoint,onClose,}: BaseModalProps & {+ /**+ * Which control opened this dialog. Required rather than defaulted: five+ * places open it, and a default would file whichever one forgot under the+ * same heading as the ones that did not.+ */+ entryPoint: UiEntryPoint;locationId?: string;/** When set, start the session as this Claude Code subagent of the agent. */agentName?: string;@@ -295,6 +303,11 @@ export const CreateSessionModal = observer(function CreateSessionModal({autoApprove: resolvedAgent.autoApprove,initialPrompt,agentName: effectiveAgentName || undefined,+ entryPoint,+ // Whether a room was asked for, never which one. Declared here because+ // the record `noteIntendedRoom` just wrote is consumed while this+ // session launches, so nothing downstream can read the answer back.+ connectedToRoom: activeRoom !== null,});navigate('session', { locationId: selectedLocationId, sessionId: id });onClose();diff --git a/console/apps/switch-console-desktop/src/renderer/features/sessions/main-panel.tsx b/console/apps/switch-console-desktop/src/renderer/features/sessions/main-panel.tsxindex 14ec2dad4..614485c32 100644--- a/console/apps/switch-console-desktop/src/renderer/features/sessions/main-panel.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/sessions/main-panel.tsx@@ -54,7 +54,7 @@ export const SessionMainPanel = observer(function SessionMainPanel() {if (kind === 'location-error') {void getLocationManagerStore().mountLocation(locationId);} else {- void getSessionManagerStore(locationId)?.provisionSession(sessionId);+ void getSessionManagerStore(locationId)?.provisionSession(sessionId, 'retry_button');}};return (diff --git a/console/apps/switch-console-desktop/src/renderer/features/sessions/stores/session-manager.ts b/console/apps/switch-console-desktop/src/renderer/features/sessions/stores/session-manager.tsindex 40c1b6fba..7dec2bc41 100644--- a/console/apps/switch-console-desktop/src/renderer/features/sessions/stores/session-manager.ts+++ b/console/apps/switch-console-desktop/src/renderer/features/sessions/stores/session-manager.ts@@ -19,6 +19,7 @@ import type {Session,SessionLifecycleStatus,} from '@shared/core/sessions/sessions';+import type { SessionProvisionTrigger } from '@shared/core/telemetry/reporting';import { sessionAgentRegistry } from './session-agent-registry';import {createUnprovisionedSession,@@ -272,7 +273,10 @@ export class SessionManagerStore {await this.provisionSession(params.id);}- async provisionSession(sessionId: string): Promise<void> {+ async provisionSession(+ sessionId: string,+ trigger: SessionProvisionTrigger = 'initial'+ ): Promise<void> {await getLocationManagerStore().mountLocation(this.locationId);await this.loadSessions();@@ -286,7 +290,7 @@ export class SessionManagerStore {session.phase = 'provision';});- const promise = this._doProvision(sessionId).finally(() => {+ const promise = this._doProvision(sessionId, trigger).finally(() => {this._provisionPromises.delete(sessionId);});@@ -294,12 +298,12 @@ export class SessionManagerStore {return promise;}- private async _doProvision(sessionId: string): Promise<void> {+ private async _doProvision(sessionId: string, trigger: SessionProvisionTrigger): Promise<void> {const session = this.sessions.get(sessionId);if (!session || !isUnprovisioned(session)) return;// Single-phase provision: session bootstrap + session provider construction + registration.- const result = await rpc.sessions.provisionSession(sessionId);+ const result = await rpc.sessions.provisionSession({ sessionId, trigger });if (!result.success) {const message = result.error.message;runInAction(() => {diff --git a/console/apps/switch-console-desktop/src/renderer/features/sessions/view.tsx b/console/apps/switch-console-desktop/src/renderer/features/sessions/view.tsxindex 67c25be97..b4123b8f9 100644--- a/console/apps/switch-console-desktop/src/renderer/features/sessions/view.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/sessions/view.tsx@@ -32,7 +32,7 @@ const SessionViewWrapperWithProviders = observer(function SessionViewWrapperWithif (sessionStore && 'archivedAt' in sessionStore.data && sessionStore.data.archivedAt) return;getSessionManagerStore(locationId)- ?.provisionSession(sessionId)+ ?.provisionSession(sessionId, 'auto').catch(() => {});}, [kind, locationId, sessionId, sessionStore]);diff --git a/console/apps/switch-console-desktop/src/renderer/features/sidebar/agent-item.tsx b/console/apps/switch-console-desktop/src/renderer/features/sidebar/agent-item.tsxindex da42d7ea1..d73c5e9aa 100644--- a/console/apps/switch-console-desktop/src/renderer/features/sidebar/agent-item.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/sidebar/agent-item.tsx@@ -194,7 +194,11 @@ export const SidebarAgentItem = observer(function SidebarAgentItem({className="opacity-0 transition-opacity duration-150 group-hover/row:opacity-100"onClick={(e) => {e.stopPropagation();- showCreateSessionModal({ locationId: agent.locationId, agentName });+ showCreateSessionModal({+ locationId: agent.locationId,+ agentName,+ entryPoint: 'sidebar',+ });}}><Plus className="h-4 w-4" />diff --git a/console/apps/switch-console-desktop/src/renderer/features/sidebar/room-agent-row.tsx b/console/apps/switch-console-desktop/src/renderer/features/sidebar/room-agent-row.tsxindex 88f685605..7297db4f4 100644--- a/console/apps/switch-console-desktop/src/renderer/features/sidebar/room-agent-row.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/sidebar/room-agent-row.tsx@@ -153,6 +153,7 @@ export const RoomAgentRow = observer(function RoomAgentRow({locationId: agent.locationId,agentName: agent.name,roomId,+ entryPoint: 'room_row',});}}>diff --git a/console/apps/switch-console-desktop/src/renderer/features/sidebar/session-item.tsx b/console/apps/switch-console-desktop/src/renderer/features/sidebar/session-item.tsxindex bd1de4908..7f6a21682 100644--- a/console/apps/switch-console-desktop/src/renderer/features/sidebar/session-item.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/sidebar/session-item.tsx@@ -48,7 +48,7 @@ export const SidebarSessionItem = observer(function SidebarSessionItem({const handleProvision = () => {if (session.state !== 'unprovisioned' || session.phase !== 'idle') return;- void sessionManager?.provisionSession(sessionId);+ void sessionManager?.provisionSession(sessionId, 'auto');};const openSession = () => {diff --git a/console/apps/switch-console-desktop/src/renderer/features/sidebar/sessions-section-header.tsx b/console/apps/switch-console-desktop/src/renderer/features/sidebar/sessions-section-header.tsxindex 8c514b33b..0e4ccdb3f 100644--- a/console/apps/switch-console-desktop/src/renderer/features/sidebar/sessions-section-header.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/sidebar/sessions-section-header.tsx@@ -322,7 +322,7 @@ export const SessionsSectionHeader = observer(function SessionsSectionHeader() {Collapse all</DropdownMenuItem><DropdownMenuSeparator />- <DropdownMenuItem onClick={() => showAddLocationModal({})}>+ <DropdownMenuItem onClick={() => showAddLocationModal({ entryPoint: 'sidebar' })}><UserPlus className="mr-1.5 h-4 w-4" />Add an agent</DropdownMenuItem>@@ -339,7 +339,7 @@ export const SessionsSectionHeader = observer(function SessionsSectionHeader() {<div className="px-2 pb-1"><buttontype="button"- onClick={() => showCreateSessionModal({})}+ onClick={() => showCreateSessionModal({ entryPoint: 'sidebar' })}className="flex w-full cursor-pointer items-center gap-[9px] rounded-lg px-[9px] py-[6px] text-sm text-foreground-muted transition-colors hover:bg-[var(--sel-soft)] hover:text-foreground"><Plus className="size-4 shrink-0" />diff --git a/console/apps/switch-console-desktop/src/renderer/features/switch-rooms/AddAgentToRoomsModal.tsx b/console/apps/switch-console-desktop/src/renderer/features/switch-rooms/AddAgentToRoomsModal.tsxindex af6a21d01..fea64a8a9 100644--- a/console/apps/switch-console-desktop/src/renderer/features/switch-rooms/AddAgentToRoomsModal.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/switch-rooms/AddAgentToRoomsModal.tsx@@ -97,6 +97,7 @@ export const AddAgentToRoomsModal = observer(function AddAgentToRoomsModal({serverId,roomId: room.id,agentIds: [switchAgentId],+ direction: 'room_to_agents',});}await switchRoomsStore.refreshRoomState();diff --git a/console/apps/switch-console-desktop/src/renderer/features/switch-rooms/AddAgentsToRoomModal.tsx b/console/apps/switch-console-desktop/src/renderer/features/switch-rooms/AddAgentsToRoomModal.tsxindex 1fb1a0ed6..f2ecff15c 100644--- a/console/apps/switch-console-desktop/src/renderer/features/switch-rooms/AddAgentsToRoomModal.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/switch-rooms/AddAgentsToRoomModal.tsx@@ -85,6 +85,7 @@ export const AddAgentsToRoomModal = observer(function AddAgentsToRoomModal({serverId,roomId,agentIds: selected.map((a) => a.id),+ direction: 'agents_to_room',});await switchRoomsStore.refreshRoomState();onSuccess();diff --git a/console/apps/switch-console-desktop/src/renderer/features/switch-rooms/room-configuration-panel.tsx b/console/apps/switch-console-desktop/src/renderer/features/switch-rooms/room-configuration-panel.tsxindex aeb5be6ce..8ee7d5198 100644--- a/console/apps/switch-console-desktop/src/renderer/features/switch-rooms/room-configuration-panel.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/switch-rooms/room-configuration-panel.tsx@@ -440,6 +440,7 @@ const AddAgentPanel = observer(function AddAgentPanel({serverId,roomId: room.id,agentIds: [switchAgentId],+ direction: 'agents_to_room',});await onAdded();} catch (cause) {diff --git a/console/apps/switch-console-desktop/src/renderer/features/switch-rooms/session-deeplink-listener.tsx b/console/apps/switch-console-desktop/src/renderer/features/switch-rooms/session-deeplink-listener.tsxindex 28dda4c8b..d699ea9c9 100644--- a/console/apps/switch-console-desktop/src/renderer/features/switch-rooms/session-deeplink-listener.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/switch-rooms/session-deeplink-listener.tsx@@ -6,6 +6,7 @@ import { getSessionManagerStore } from '@renderer/features/sessions/stores/sessiimport { events } from '@renderer/lib/ipc';import { scopeToLocationServer } from '@renderer/lib/layout/scope-to-server';import { appState } from '@renderer/lib/stores/app-state';+import { report } from '@renderer/lib/telemetry/report';import { sessionDeeplinkChannel } from '@shared/core/switch-rooms/switchRoomEvents';import { pickDeeplinkTarget } from './session-deeplink-resolve';import { switchRoomsStore as roomConnectionsStore } from './switch-rooms-store';@@ -57,41 +58,48 @@ export function SessionDeeplinkListener(): null {useEffect(() => {roomConnectionsStore.ensureLoaded();void agentsStore.load();- return events.on(sessionDeeplinkChannel, ({ agentId, roomId, server, sessionId }) => {- void (async () => {- const match = pickDeeplinkTarget(- sessionId,- () => findSessionById(sessionId),- () => findSessionForRoom(roomId)- );- if (!match) {- console.warn('[deeplink] no local session for deeplink', {+ return events.on(+ sessionDeeplinkChannel,+ ({ agentId, roomId, server, sessionId, coldStart }) => {+ void (async () => {+ const match = pickDeeplinkTarget(sessionId,+ () => findSessionById(sessionId),+ () => findSessionForRoom(roomId)+ );+ // Reported here rather than in the main process: whether this install+ // actually has the linked session is the question worth asking, and only+ // the renderer can answer it.+ report('deeplink_opened', { resolved: match !== null, cold_start: coldStart });+ if (!match) {+ console.warn('[deeplink] no local session for deeplink', {+ sessionId,+ roomId,+ agentId,+ server,+ });+ toast.error('No agent session found for this link', {+ description:+ 'This copy of Switch Console has no local session for the linked room. Open it on the client running that agent.',+ });+ return;+ }+ console.info('[deeplink] navigating to session', {+ linkSessionId: sessionId,+ matchedSessionId: match.sessionId,+ matchedVia: sessionId ? 'session-id' : 'room',+ locationId: match.locationId,roomId,- agentId,- server,});- toast.error('No agent session found for this link', {- description:- 'This copy of Switch Console has no local session for the linked room. Open it on the client running that agent.',- });- return;- }- console.info('[deeplink] navigating to session', {- linkSessionId: sessionId,- matchedSessionId: match.sessionId,- matchedVia: sessionId ? 'session-id' : 'room',- locationId: match.locationId,- roomId,- });- // Scope the sidebar to the session's server first; otherwise its location- // is filtered out of the server-scoped tree and there is no row to- // reveal. Navigating is all the sidebar needs — it expands and scrolls- // to whatever the open view selects, from any origin.- await scopeToLocationServer(match.locationId);- appState.navigation.navigate('session', match);- })();- });+ // Scope the sidebar to the session's server first; otherwise its location+ // is filtered out of the server-scoped tree and there is no row to+ // reveal. Navigating is all the sidebar needs — it expands and scrolls+ // to whatever the open view selects, from any origin.+ await scopeToLocationServer(match.locationId);+ appState.navigation.navigate('session', match);+ })();+ }+ );}, []);return null;}diff --git a/console/apps/switch-console-desktop/src/renderer/features/switch-servers/AddServerModal.tsx b/console/apps/switch-console-desktop/src/renderer/features/switch-servers/AddServerModal.tsxindex bd873ac5e..36ba3b7c0 100644--- a/console/apps/switch-console-desktop/src/renderer/features/switch-servers/AddServerModal.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/switch-servers/AddServerModal.tsx@@ -1,11 +1,12 @@import { CircleCheck, Globe, Laptop, Server, TriangleAlert } from 'lucide-react';import { observer } from 'mobx-react-lite';-import { useCallback, useEffect, useState } from 'react';+import { useCallback, useEffect, useRef, useState } from 'react';import { HostReachabilityNotice } from '@renderer/features/remote-hosts/host-reachability-notice';import { toast } from '@renderer/lib/hooks/use-toast';import { rpc } from '@renderer/lib/ipc';import { useNavigate } from '@renderer/lib/layout/navigation-provider';import { type BaseModalProps } from '@renderer/lib/modal/modal-provider';+import { report } from '@renderer/lib/telemetry/report';import { Alert, AlertDescription, AlertTitle } from '@renderer/lib/ui/alert';import { Button } from '@renderer/lib/ui/button';import { ConfirmButton } from '@renderer/lib/ui/confirm-button';@@ -19,6 +20,10 @@ import { Field, FieldGroup, FieldLabel } from '@renderer/lib/ui/field';import { Input } from '@renderer/lib/ui/input';import { Spinner } from '@renderer/lib/ui/spinner';import { WizardStepHeader } from '@renderer/lib/ui/wizard-step-header';+import type {+ AddServerChoiceName,+ AddServerStepName,+} from '@shared/core/switch-servers/add-server-steps';import type {ServerApiUrlPropagation,SwitchServer,@@ -74,6 +79,18 @@ type Props = BaseModalProps<void> & {type Step = 'choose' | 'local' | 'remoteHost' | 'external' | 'signIn' | 'linkAccounts';+/**+ * This wizard's steps and the shared list of step names say the same thing.+ *+ * The list is what a drop-off is reported against and cannot import a component.+ * Asserted both ways, so adding a step without naming it there — or leaving a+ * name behind after removing one — fails to compile.+ */+const _stepsAreExhaustive: AddServerStepName extends Step ? true : never = true;+const _stepsAreComplete: Step extends AddServerStepName ? true : never = true;+void _stepsAreExhaustive;+void _stepsAreComplete;+/*** How many steps connecting to a server someone else runs takes: choose that* path, point at the server, sign in, then say which messaging account is you.@@ -95,9 +112,69 @@ const CONNECT_STEPS = 4;* those two steps follow in the same dialog rather than waiting on the server's* page to be discovered (CHOO-2164).*/+/**+ * The path each step belongs to, or null for the steps that inherit whatever+ * was chosen before them.+ *+ * The chooser is `none` rather than null, and the difference is the whole point+ * of the column: arriving at the chooser is arriving with nothing chosen, which+ * is as true of pressing Back as it is of opening the wizard. Carrying the+ * abandoned path forwards would make a return read as progress along it.+ */+const CHOICE_FOR_STEP: Record<Step, AddServerChoiceName | null> = {+ choose: 'none',+ local: 'local',+ remoteHost: 'remoteHost',+ external: 'external',+ signIn: null,+ linkAccounts: null,+};+export const AddServerModal = observer(function AddServerModal(props: Props) {const isEdit = props.serverId != null;- const [step, setStep] = useState<Step>(isEdit ? 'external' : (props.mode ?? 'choose'));+ const openedAt: Step = isEdit ? 'external' : (props.mode ?? 'choose');+ const openedWith = CHOICE_FOR_STEP[openedAt] ?? 'none';+ const [step, setStep] = useState<Step>(openedAt);+ // Which path was taken at the chooser, carried so every later step can be+ // attributed to it. `none` while still on the chooser, which is what makes a+ // drop-off before choosing distinguishable from one after.+ const [choice, setChoice] = useState<AddServerChoiceName>(openedWith);++ /**+ * Report the step the wizard opened on.+ *+ * The steps below are reported as they are reached, so without this the first+ * one — the one every later step is measured against — is the only one never+ * counted, and the funnel has no denominator. The ref rather than the+ * dependency list is what holds it to a single report: strict mode mounts+ * every effect twice, and a wizard that opens twice per opening would put the+ * denominator out by a factor of two in development builds.+ *+ * Editing is not one of the steps. It borrows the same form to change a+ * server that already exists, reaches no step after this one, and counting it+ * would put arrivals in the funnel that were never adding anything.+ */+ const reportedOpening = useRef(false);+ useEffect(() => {+ if (isEdit || reportedOpening.current) return;+ reportedOpening.current = true;+ report('add_server_step', { step: openedAt, choice: openedWith });+ }, [isEdit, openedAt, openedWith]);++ /**+ * Move to a step, and report reaching it.+ *+ * One function rather than nine `setStep` calls: the wizard's back buttons go+ * through the same state, so instrumenting each site would count returning to+ * the chooser as reaching it again and make the funnel read as if people+ * restarted rather than gave up.+ */+ const goToStep = (next: Step) => {+ const nextChoice = CHOICE_FOR_STEP[next] ?? choice;+ setChoice(nextChoice);+ setStep(next);+ report('add_server_step', { step: next, choice: nextChoice });+ };// The server the wizard just created, and the subject of every step after// it. Null in edit mode and on the two managed paths, which is what// distinguishes the standalone edit form from step 2 of the wizard.@@ -122,9 +199,9 @@ export const AddServerModal = observer(function AddServerModal(props: Props) {if (step === 'choose') {return (<ChooseStep- onLocal={() => setStep('local')}- onRemoteHost={() => setStep('remoteHost')}- onExternal={() => setStep('external')}+ onLocal={() => goToStep('local')}+ onRemoteHost={() => goToStep('remoteHost')}+ onExternal={() => goToStep('external')}onClose={props.onClose}/>);@@ -132,7 +209,7 @@ export const AddServerModal = observer(function AddServerModal(props: Props) {if (step === 'local') {return (<LocalSetupStep- onBack={isEdit ? undefined : () => setStep('choose')}+ onBack={isEdit ? undefined : () => goToStep('choose')}onDone={finish}onClose={props.onClose}/>@@ -141,7 +218,7 @@ export const AddServerModal = observer(function AddServerModal(props: Props) {if (step === 'remoteHost') {return (<RemoteHostSetupStep- onBack={() => setStep('choose')}+ onBack={() => goToStep('choose')}onDone={finish}onClose={props.onClose}/>@@ -151,9 +228,9 @@ export const AddServerModal = observer(function AddServerModal(props: Props) {return (<SignInStepserver={connected}- onBack={() => setStep('external')}+ onBack={() => goToStep('external')}onClose={props.onClose}- onSignedIn={() => setStep('linkAccounts')}+ onSignedIn={() => goToStep('linkAccounts')}/>);}@@ -173,10 +250,10 @@ export const AddServerModal = observer(function AddServerModal(props: Props) {{...props}isEdit={isEdit}existing={connected}- onBack={isEdit ? undefined : () => setStep('choose')}+ onBack={isEdit ? undefined : () => goToStep('choose')}onConnected={(server) => {setConnected(server);- setStep('signIn');+ goToStep('signIn');}}/>);diff --git a/console/apps/switch-console-desktop/src/renderer/features/switch-servers/server-agents-view.tsx b/console/apps/switch-console-desktop/src/renderer/features/switch-servers/server-agents-view.tsxindex 6680b64e0..d8cd684d2 100644--- a/console/apps/switch-console-desktop/src/renderer/features/switch-servers/server-agents-view.tsx+++ b/console/apps/switch-console-desktop/src/renderer/features/switch-servers/server-agents-view.tsx@@ -65,7 +65,7 @@ const ServerAgentsPanel = observer(function ServerAgentsPanel() {<div className="grid grid-cols-[repeat(auto-fill,minmax(180px,1fr))] gap-[14px]"><buttontype="button"- onClick={() => showAddAgentModal({})}+ onClick={() => showAddAgentModal({ entryPoint: 'server_page' })}className="flex min-h-[184px] cursor-pointer items-center justify-center rounded-[11px] border border-dashed border-border text-foreground-muted transition-colors hover:border-border-1 hover:bg-[var(--sel-soft)] hover:text-foreground"aria-label="Add agent">diff --git a/console/apps/switch-console-desktop/src/renderer/lib/commands/app-commands.ts b/console/apps/switch-console-desktop/src/renderer/lib/commands/app-commands.tsindex 9ce4b00aa..ae6b92790 100644--- a/console/apps/switch-console-desktop/src/renderer/lib/commands/app-commands.ts+++ b/console/apps/switch-console-desktop/src/renderer/lib/commands/app-commands.ts@@ -48,7 +48,7 @@ function createAppCommandProvider(): CommandProvider {shortcutKey: newLocationDef.shortcutKey,group: newLocationDef.group,execute() {- showModal('addAgentModal', {});+ showModal('addAgentModal', { entryPoint: 'command_palette' });},},{diff --git a/console/apps/switch-console-desktop/src/renderer/lib/commands/registry.ts b/console/apps/switch-console-desktop/src/renderer/lib/commands/registry.tsindex 068d4f9ed..b4190d9f0 100644--- a/console/apps/switch-console-desktop/src/renderer/lib/commands/registry.ts+++ b/console/apps/switch-console-desktop/src/renderer/lib/commands/registry.ts@@ -1,6 +1,8 @@import { comparer, makeAutoObservable, reaction } from 'mobx';import type { ShortcutSettingsKey } from '@renderer/lib/hooks/useKeyboardShortcuts';import { appState } from '@renderer/lib/stores/app-state';+import { report } from '@renderer/lib/telemetry/report';+import type { CommandId } from '@shared/commands';import { SCOPE_LEVELS, type AppCommand, type CommandProvider, type ScopeId } from './types';class CommandRegistry {@@ -28,6 +30,7 @@ class CommandRegistry {.getCommands().find((c) => c.shortcutKey === shortcutKey && c.enabled !== false);if (cmd) {+ report('command_executed', { command_id: cmd.id as CommandId, invoked_by: 'shortcut' });cmd.execute();return true;}diff --git a/console/apps/switch-console-desktop/src/renderer/lib/components/error-boundary.tsx b/console/apps/switch-console-desktop/src/renderer/lib/components/error-boundary.tsxindex 3d3df80a7..6b1f5f217 100644--- a/console/apps/switch-console-desktop/src/renderer/lib/components/error-boundary.tsx+++ b/console/apps/switch-console-desktop/src/renderer/lib/components/error-boundary.tsx@@ -1,4 +1,5 @@import React from 'react';+import { report } from '@renderer/lib/telemetry/report';import { log } from '@renderer/utils/logger';import { rpc } from '../ipc';import { Button } from '../ui/button';@@ -47,6 +48,9 @@ export class ErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoun* record of left none.*/componentDidCatch(error: Error, info: React.ErrorInfo) {+ // A count only. The message, the stack and the component stack all stay in+ // the local log — none of them may leave the machine.+ report('renderer_crashed', {});log.error('Renderer crashed', {event: 'renderer_crash',error: { name: error.name, message: error.message, stack: error.stack },diff --git a/console/apps/switch-console-desktop/src/renderer/lib/stores/navigation-store.ts b/console/apps/switch-console-desktop/src/renderer/lib/stores/navigation-store.tsindex 228e1117a..b3e4a018a 100644--- a/console/apps/switch-console-desktop/src/renderer/lib/stores/navigation-store.ts+++ b/console/apps/switch-console-desktop/src/renderer/lib/stores/navigation-store.ts@@ -2,6 +2,7 @@ import { makeAutoObservable, toJS } from 'mobx';import { type GuardResult, type ViewId, type WrapParams } from '@renderer/app/view-registry';import type { NonSettingsViewId } from '@renderer/lib/layout/navigation-provider';import { modalStore } from '@renderer/lib/modal/modal-store';+import { report } from '@renderer/lib/telemetry/report';import type { NavigationSnapshot } from '@shared/view-state';import { appState } from './app-state';import type { Snapshottable } from './snapshottable';@@ -68,6 +69,10 @@ export class NavigationStore implements Snapshottable<NavigationSnapshot> {}if (viewId !== this.currentViewId) {+ // Inside the changed check: re-navigating to the screen you are already on+ // is not opening it, and counting it would make the busiest view the one+ // people revisit rather than the one they use.+ report('view_opened', { view_id: viewId });this.currentViewId = viewId;if (viewId !== 'settings') {this.lastNonSettingsView = viewId;@@ -125,5 +130,15 @@ export class NavigationStore implements Snapshottable<NavigationSnapshot> {this.viewParamsStore = { ...this.viewParamsStore, [guard.redirect]: guard.params };}}++ // The screen a session resumes on is arrived at rather than navigated to, so+ // `_applyNavigation` never sees it and nobody would be counted as having+ // opened it — someone who works all afternoon in a restored session would+ // report no screen at all. Reported once, here at the end, so a snapshot the+ // guard sends back counts the screen the user lands on rather than both it+ // and the one that was persisted. `currentViewId` has settled by now, which+ // is also what keeps a later navigation to the same screen from counting a+ // second opening.+ report('view_opened', { view_id: this.currentViewId });}}diff --git a/console/apps/switch-console-desktop/src/renderer/lib/stores/update-store.ts b/console/apps/switch-console-desktop/src/renderer/lib/stores/update-store.tsindex e2a5134c5..f29af34df 100644--- a/console/apps/switch-console-desktop/src/renderer/lib/stores/update-store.ts+++ b/console/apps/switch-console-desktop/src/renderer/lib/stores/update-store.ts@@ -219,7 +219,7 @@ export class UpdateStore {// download continues in the background.void this._resyncFromMain().then(() => {if (IN_FLIGHT_STATUSES.has(this.state.status)) return;- rpc.update.check().catch(() => {});+ rpc.update.check('startup').catch(() => {});});}diff --git a/console/apps/switch-console-desktop/src/renderer/lib/telemetry/report.ts b/console/apps/switch-console-desktop/src/renderer/lib/telemetry/report.tsnew file mode 100644index 000000000..5628dea89--- /dev/null+++ b/console/apps/switch-console-desktop/src/renderer/lib/telemetry/report.ts@@ -0,0 +1,26 @@+import type { RendererTelemetryEvents } from '@shared/core/telemetry/renderer-events';++/**+ * Report something the interface observed.+ *+ * Fire-and-forget, like its counterpart in the main process: it is never+ * awaited and never throws, so nothing a user is doing can be slowed or broken+ * by reporting it. The rejection is swallowed on purpose — there is no failure+ * here a screen could act on, and the main process logs the reason.+ *+ * What may be reported, and which values each event accepts, is decided in the+ * main process. This is only the way to ask.+ *+ * The channel is imported when something is actually reported, not when this+ * module is loaded. The renderer's client reads `window` as it initialises, so a+ * static import would drag a browser global into every module that might one day+ * report — including the ones exercised without a DOM.+ */+export function report<K extends keyof RendererTelemetryEvents>(+ name: K,+ properties: RendererTelemetryEvents[K]+): void {+ void import('@renderer/lib/ipc')+ .then(({ rpc }) => rpc.telemetry.track({ name, properties }))+ .catch(() => {});+}diff --git a/console/apps/switch-console-desktop/src/renderer/main.tsx b/console/apps/switch-console-desktop/src/renderer/main.tsxindex 223a20517..cb7a67a5e 100644--- a/console/apps/switch-console-desktop/src/renderer/main.tsx+++ b/console/apps/switch-console-desktop/src/renderer/main.tsx@@ -38,7 +38,12 @@ async function bootstrap() {viewStateCache.populate(allViewState as Record<string, unknown>);setupNavigationGuards();- if (navResult) appState.navigation.restoreSnapshot(navResult);+ // Restored even with nothing to restore, so the screen the app settles on is+ // always the one it announces having opened. A snapshot is only written once+ // something changes, so an install where nobody navigates away from home has+ // none — and skipping the call would leave that install having opened no+ // screen at all.+ appState.navigation.restoreSnapshot(navResult ?? {});setupAppCommandProvider();setupViewCommandProvider(views as unknown as ViewCommandProviders);wireMouseNavigation();diff --git a/console/apps/switch-console-desktop/src/shared/core/sessions/sessions.ts b/console/apps/switch-console-desktop/src/shared/core/sessions/sessions.tsindex 3722559ee..ae8eefd58 100644--- a/console/apps/switch-console-desktop/src/shared/core/sessions/sessions.ts+++ b/console/apps/switch-console-desktop/src/shared/core/sessions/sessions.ts@@ -1,6 +1,7 @@import z from 'zod';import type { AgentProviderId } from '@shared/core/providers/agent-provider-registry';import type { AgentStatus } from '@shared/core/providers/agentEvents';+import type { SessionStartSource, UiEntryPoint } from '@shared/core/telemetry/reporting';import type { TerminalShellId } from '@shared/core/terminals/terminal-settings';export const MAX_SESSION_TITLE_LENGTH = 100;@@ -85,6 +86,27 @@ export type CreateSessionParams = {* relay) but gets no PTY until someone views it.*/attach?: boolean;+ /**+ * Which control the user started the session from, for reporting. Omitted by+ * callers with no user behind them, which report as `unknown`.+ */+ entryPoint?: UiEntryPoint;+ /**+ * Who started the session: a person, the app on their behalf, or a remote host+ * that was already running one. Omitted reports as `unknown` rather than+ * assuming a person was there.+ */+ startSource?: SessionStartSource;+ /**+ * Whether a Switch room was chosen for this session before it was created,+ * for reporting. Never which room.+ *+ * Declared by the caller rather than read back, because the record that would+ * answer it is consumed during the launch this session is part of: the+ * poller's intended-room entry is claimed by `ensureForSession` while+ * `createSession` is still running, so anything asking afterwards is told no.+ */+ connectedToRoom?: boolean;};export type CreateSessionError =diff --git a/console/apps/switch-console-desktop/src/shared/core/settings/setting-keys.ts b/console/apps/switch-console-desktop/src/shared/core/settings/setting-keys.tsnew file mode 100644index 000000000..9937db410--- /dev/null+++ b/console/apps/switch-console-desktop/src/shared/core/settings/setting-keys.ts@@ -0,0 +1,31 @@+/**+ * The names of the app's settings groups.+ *+ * Written out rather than derived from the schema map, because this list is+ * what a setting change is reported against and it must be a closed set of+ * literals — a type derived from a `Record` widens to `string` at the boundary+ * the value crosses, and a `string` in a payload is exactly what the catalogue+ * exists to prevent.+ *+ * The schema map asserts at compile time that it and this list agree, so adding+ * a settings group without naming it here fails the build.+ */+export const APP_SETTINGS_KEYS = [+ 'localLocation',+ 'location',+ 'sessions',+ 'defaultAgent',+ 'notifications',+ 'theme',+ 'openIn',+ 'interface',+ 'terminal',+ 'browserPreview',+ 'browser',+ 'changesViewMode',+ 'remote',+ 'onboarding',+ 'telemetry',+] as const;++export type AppSettingsKeyName = (typeof APP_SETTINGS_KEYS)[number];diff --git a/console/apps/switch-console-desktop/src/shared/core/switch-rooms/switchRoomEvents.ts b/console/apps/switch-console-desktop/src/shared/core/switch-rooms/switchRoomEvents.tsindex f09cbfdf5..9575a5627 100644--- a/console/apps/switch-console-desktop/src/shared/core/switch-rooms/switchRoomEvents.ts+++ b/console/apps/switch-console-desktop/src/shared/core/switch-rooms/switchRoomEvents.ts@@ -24,4 +24,10 @@ export const sessionDeeplinkChannel = defineEvent<{/** Shared session id, preferred for resolution (resolves on any client);* empty string for links from older builds that only carried the room. */sessionId: string;+ /**+ * Whether the link started the app rather than being handed to a running one.+ * Known only in the main process; carried here because whether the link+ * resolved is known only in the renderer, and both belong to one event.+ */+ coldStart: boolean;}>('switch-room:session-deeplink');diff --git a/console/apps/switch-console-desktop/src/shared/core/switch-servers/add-server-steps.ts b/console/apps/switch-console-desktop/src/shared/core/switch-servers/add-server-steps.tsnew file mode 100644index 000000000..9dc9f3228--- /dev/null+++ b/console/apps/switch-console-desktop/src/shared/core/switch-servers/add-server-steps.ts@@ -0,0 +1,27 @@+/**+ * The steps of the add-server wizard, and the path chosen at its first screen.+ *+ * Named here rather than in the modal because where people stop is reported+ * from the main process, which cannot import a React component. The modal+ * asserts at compile time that its own step union is exactly this list.+ */+export const ADD_SERVER_STEPS = [+ 'choose',+ 'local',+ 'remoteHost',+ 'external',+ 'signIn',+ 'linkAccounts',+] as const;++export type AddServerStepName = (typeof ADD_SERVER_STEPS)[number];++/**+ * Which kind of server the wizard is setting up.+ *+ * `none` is the first screen, where nothing has been chosen yet — so a drop-off+ * before choosing is distinguishable from one after.+ */+export const ADD_SERVER_CHOICES = ['none', 'local', 'remoteHost', 'external'] as const;++export type AddServerChoiceName = (typeof ADD_SERVER_CHOICES)[number];diff --git a/console/apps/switch-console-desktop/src/shared/core/telemetry/renderer-events.ts b/console/apps/switch-console-desktop/src/shared/core/telemetry/renderer-events.tsnew file mode 100644index 000000000..c4302d099--- /dev/null+++ b/console/apps/switch-console-desktop/src/shared/core/telemetry/renderer-events.ts@@ -0,0 +1,55 @@+import type { CommandId } from '@shared/commands';+import type { OnboardingStepId } from '@shared/core/onboarding/checklist';+import type {+ AddServerChoiceName,+ AddServerStepName,+} from '@shared/core/switch-servers/add-server-steps';+import type { ViewIdName } from '@shared/core/views/view-ids';++/**+ * What the interface may report, as the call sites see it.+ *+ * The catalogue in the main process is still the definition of these events;+ * this is the same shape stated where the renderer can reach it, since the two+ * processes share no types. The main process asserts that they agree, so the+ * pair cannot drift — a property added on one side without the other fails the+ * build.+ *+ * Every value is a closed literal. A `string` here would defeat the check on the+ * other side, which is the only thing standing between a value that crossed a+ * process boundary and a payload.+ */+export type RendererTelemetryEvents = {+ /** A screen was opened. */+ view_opened: { view_id: ViewIdName };+ /**+ * A command was run, and how it was reached.+ *+ * No `menu` here: the application menu talks to the interface over its own+ * channels and never reaches a command, so a menu value would be one that can+ * never occur — a gap in a dashboard that looks like a finding.+ */+ command_executed: {+ command_id: CommandId;+ invoked_by: 'palette' | 'shortcut';+ };+ /**+ * A `switch://` link was opened. `resolved` says whether this install actually+ * had the session or room the link named, which is the question worth asking;+ * `cold_start` distinguishes a link that launched the app from one handed to a+ * running window, because they fail differently.+ */+ deeplink_opened: { resolved: boolean; cold_start: boolean };+ /** Someone began a step of the first-run checklist. */+ onboarding_step_started: { step_id: OnboardingStepId };+ /** The checklist was dismissed without finishing it. */+ onboarding_checklist_dismissed: Record<never, never>;+ /** Every step of the checklist is done. */+ onboarding_completed: Record<never, never>;+ /** The add-server wizard reached a step. Where people stop is the question. */+ add_server_step: { step: AddServerStepName; choice: AddServerChoiceName };+ /** A screen failed and the error boundary caught it. */+ renderer_crashed: Record<never, never>;+};++export type RendererTelemetryEventName = keyof RendererTelemetryEvents;diff --git a/console/apps/switch-console-desktop/src/shared/core/telemetry/reporting.ts b/console/apps/switch-console-desktop/src/shared/core/telemetry/reporting.tsnew file mode 100644index 000000000..28818c838--- /dev/null+++ b/console/apps/switch-console-desktop/src/shared/core/telemetry/reporting.ts@@ -0,0 +1,84 @@+/**+ * Dimensions the UI supplies to reported events.+ *+ * They live here, rather than in the telemetry module, because the renderer has+ * to name them at the point the user acts and the main process has to put them+ * in a payload — and neither may import the other's internals. Both the union+ * and the value list are exported: the union types the call sites, and the list+ * is what the renderer boundary checks a received value against, since a type+ * proves nothing about a value that crossed a process.+ *+ * Every value is a closed literal. Nothing here may become a `string`.+ */++/**+ * Which control the user reached an action from.+ *+ * Each variant is a real place in the UI that opens the relevant dialog, so a+ * value that stops being reachable shows up as a count that falls to zero rather+ * than as one nobody can place. `unknown` covers a path that did not say — a+ * machine-initiated action, or a caller added without one.+ */+export const UI_ENTRY_POINTS = [+ 'command_palette',+ 'sidebar',+ 'server_page',+ 'onboarding',+ 'agent_page',+ 'session_list',+ 'room_row',+ 'unknown',+] as const;++export type UiEntryPoint = (typeof UI_ENTRY_POINTS)[number];++/**+ * Who started a session.+ *+ * `user` is a person pressing something in this app. `auto` is the app starting+ * one on their behalf — an agent addressed in a Switch room with no live session+ * gets one, and nobody touched the desktop app at all. `adopted` is an agent+ * already running on a remote host that the app discovered and took over.+ * `unknown` is a caller that did not say.+ *+ * None of the four are comparable, so they are kept apart rather than summed. An+ * adopted session is stamped when the app *noticed* it — which is when the app+ * next ran, not when the agent started — and two installs watching one host each+ * adopt and report the same session. `auto` is separated for a blunter reason:+ * on an active team it is the commonest way a session starts, so folding it into+ * `user` would make most of the "people started a session" count automation.+ */+export const SESSION_START_SOURCES = ['user', 'auto', 'adopted', 'unknown'] as const;++export type SessionStartSource = (typeof SESSION_START_SOURCES)[number];++/**+ * What asked for a session to be provisioned.+ *+ * `initial` is the first attempt for a session and is not reported — only a+ * retry answers "did it work the second time". The other two are both retries+ * of a session that is already sitting there unprovisioned: `retry_button` is+ * someone pressing it, `auto` is the view trying again on its own when the+ * session is opened. They are counted apart because only the first is intent.+ */+export const SESSION_PROVISION_TRIGGERS = ['initial', 'auto', 'retry_button'] as const;++export type SessionProvisionTrigger = (typeof SESSION_PROVISION_TRIGGERS)[number];++/**+ * What removed an agent: a person, or a server teardown sweeping every agent on+ * it. Declared here for the same reason as the rest — the renderer names it.+ */+export const AGENT_REMOVE_TRIGGERS = ['user', 'server_teardown'] as const;++export type AgentRemoveTrigger = (typeof AGENT_REMOVE_TRIGGERS)[number];++/** Which way round agents and rooms were joined. */+export const ROOM_AGENTS_DIRECTIONS = ['agents_to_room', 'room_to_agents'] as const;++export type RoomAgentsDirection = (typeof ROOM_AGENTS_DIRECTIONS)[number];++/** What asked for an update check. */+export const UPDATE_TRIGGERS = ['user', 'startup', 'scheduled'] as const;++export type UpdateTrigger = (typeof UPDATE_TRIGGERS)[number];diff --git a/console/apps/switch-console-desktop/src/shared/core/views/view-ids.ts b/console/apps/switch-console-desktop/src/shared/core/views/view-ids.tsnew file mode 100644index 000000000..e389cb56d--- /dev/null+++ b/console/apps/switch-console-desktop/src/shared/core/views/view-ids.ts@@ -0,0 +1,23 @@+/**+ * Every screen the app can show, by id.+ *+ * The view registry is the real definition, but it cannot be imported here: it+ * holds React components, and this list has to be readable from the main+ * process. So the names are written out once, and the registry asserts at+ * compile time that its own keys are exactly these — adding a view without+ * adding it here fails the build rather than reporting a screen nobody named.+ */+export const VIEW_IDS = [+ 'home',+ 'location',+ 'session',+ 'room',+ 'settings',+ 'server',+ 'serverAgents',+ 'serverRooms',+ 'remoteHosts',+ 'remoteHost',+] as const;++export type ViewIdName = (typeof VIEW_IDS)[number];