Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

feat(console): extend telemetry to the remaining user events (CHOO-2285) (#280)

Christian McDermottd7964885d00a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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-24
diff --git a/console/AGENTS.md b/console/AGENTS.md
index 25f87659e..86c148783 100644
--- a/console/AGENTS.md
+++ b/console/AGENTS.md
@@ -417,9 +417,11 @@ pnpm run lint
Flipping 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 not
enough — excess-property checking does not apply through a spread — so the runtime
filter 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 lint
agent, room, project, location or server names or ids. Widening this is a consent
decision — 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 no
retry: 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 prompt
and no access to this setting, so sessions it starts are not counted. Do not "fix" that
by 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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<OnboardA
let 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<OnboardA
switchAgent = 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.ts
index 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.ts
index 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-ht
import { 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.ts
new file mode 100644
index 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.ts
index 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-tmux
const 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 between
diff --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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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): strin
switch (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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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-in
diff --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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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-h
import { 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.ts
index 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/a
import { 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 the
diff --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.ts
index 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 one
diff --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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.tsx
index 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.ts
index 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.tsx
index 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.tsx
index 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 }: AddLoc
autoApprove: 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.tsx
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.tsx
index 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 SidebarOnboardingChe
collapsed={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.ts
index 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.tsx
index 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)
<Input
value={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 === 0
diff --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.tsx
index 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.tsx
index 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.ts
index 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.tsx
index 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 SessionViewWrapperWith
if (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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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">
<button
type="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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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/sessi
import { 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.tsx
index 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 (
<SignInStep
server={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.tsx
index 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]">
<button
type="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.ts
index 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.ts
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.tsx
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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];