Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
fix(telemetry): dashboard accuracy — session events, message counts, preconfigured connectors, session_started (#558)
Christian McDermott0cb6d99f806a
diff --git a/console/AGENTS.md b/console/AGENTS.mdindex 52fcbfb2d..4fc5dcc2f 100644--- a/console/AGENTS.md+++ b/console/AGENTS.md@@ -483,9 +483,12 @@ pnpm run lintdistribution. 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.+- **The sidecar sends nothing to the relay.** 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 in+ this app's telemetry. Do not "fix" that by having it report; the gate is not reachable+ from there. What a session host does tell is the Switch server it already works for:+ that a new session started and how (`host/session-start.ts`), as ordinary traffic to+ that server. Whether that leaves the server as telemetry is the server's own setting.- **Redaction is split by destination, and both halves must be preserved:**- **Secrets** (tokens, keys, JWTs, PEM blocks, URL credentials) are redacted on thewrite path by `redactSecrets()` and must never reach disk.diff --git a/console/apps/switch-console-desktop/src/main/core/agent-runtime/types.ts b/console/apps/switch-console-desktop/src/main/core/agent-runtime/types.tsindex 7db9fa60a..90e608e24 100644--- a/console/apps/switch-console-desktop/src/main/core/agent-runtime/types.ts+++ b/console/apps/switch-console-desktop/src/main/core/agent-runtime/types.ts@@ -1,3 +1,4 @@+import type { HostStartSource } from '@switch-console/agent-providers';import type { Session } from '@shared/core/sessions/sessions';export interface AgentRuntimeProvider {@@ -5,7 +6,17 @@ export interface AgentRuntimeProvider {/** The session's host came up after all, so a failed start no longer stands. */hostCameUp?(): void;restart(session: Session): Promise<void>;- start(session: Session, isResuming?: boolean, initialPrompt?: string): Promise<void>;+ /**+ * `startSource` is how a new session came to start, which its host reports+ * to Switch once; null for a session that is not new or a caller that+ * cannot say.+ */+ start(+ session: Session,+ isResuming?: boolean,+ initialPrompt?: string,+ startSource?: HostStartSource | null+ ): Promise<void>;/*** Release the Console view while execution continues on the host.*/diff --git a/console/apps/switch-console-desktop/src/main/core/sdk-host/local-host.test.ts b/console/apps/switch-console-desktop/src/main/core/sdk-host/local-host.test.tsindex ada34c421..24d52714f 100644--- a/console/apps/switch-console-desktop/src/main/core/sdk-host/local-host.test.ts+++ b/console/apps/switch-console-desktop/src/main/core/sdk-host/local-host.test.ts@@ -34,8 +34,13 @@ vi.mock('@main/core/agent-runtime/impl/resolve-sidecar-bundle', () => ({}));vi.mock('@main/lib/logger', () => ({ log: { error: vi.fn(), warn: vi.fn() } }));-const { startLocalWatcher, localWatcherRoot, localWatcherControl, readLocalHostFailure } =- await import('./local-host');+const {+ startLocalSession,+ startLocalWatcher,+ localWatcherRoot,+ localWatcherControl,+ readLocalHostFailure,+} = await import('./local-host');const roots: string[] = [];let home: string;@@ -147,3 +152,33 @@ it('gives the watcher the control Console moves this agent’s sessions through'expect(mocks.runWatcher.mock.calls[0][4]).toBe(localWatcherControl('switch-agent-1'));expect(localWatcherControl('switch-agent-2')).not.toBe(localWatcherControl('switch-agent-1'));});++it('hands a local session’s launch how it started, so its host can tell Switch', async () => {+ mocks.ensure.mockResolvedValue({ created: true });+ const config = { session: { sessionId: 'session-1', agentId: 'agent-1' } } as never;++ await startLocalSession('/sessions/session-1', config, {+ resuming: false,+ restart: false,+ startSource: 'user',+ });++ expect(mocks.ensure).toHaveBeenCalledWith(+ expect.objectContaining({+ root: '/sessions/session-1',+ watcher: false,+ resuming: false,+ restart: false,+ startSource: 'user',+ })+ );+});++it('starts the watcher with no start source, since it is not a session', async () => {+ await startLocalWatcher({ session: { sessionId: 'watcher', agentId: 'agent-1' } } as never, {+ intent: 'explicit',+ spawning: true,+ });++ expect(mocks.ensure.mock.calls[0]![0]).toMatchObject({ watcher: true, startSource: null });+});diff --git a/console/apps/switch-console-desktop/src/main/core/sdk-host/local-host.ts b/console/apps/switch-console-desktop/src/main/core/sdk-host/local-host.tsindex 1543868c8..eeb6f2b58 100644--- a/console/apps/switch-console-desktop/src/main/core/sdk-host/local-host.ts+++ b/console/apps/switch-console-desktop/src/main/core/sdk-host/local-host.ts@@ -6,6 +6,7 @@ import { join } from 'node:path';import {clearTakenOver,ensureSharedProcess,+ type HostStartSource,runSharedWatcher,sharedConfigSchema,type SharedHostConfig,@@ -216,7 +217,7 @@ export const consoleSupervision: Supervision = {export async function startLocalSession(root: string,config: SharedHostConfig,- options: { resuming: boolean; restart: boolean }+ options: { resuming: boolean; restart: boolean; startSource: HostStartSource | null }): Promise<void> {await ensureSharedProcess({root,@@ -225,6 +226,7 @@ export async function startLocalSession(watcher: false,restart: options.restart,supervision: consoleSupervision,+ startSource: options.startSource,});}@@ -281,6 +283,7 @@ export async function startLocalWatcher(resuming: false,watcher: true,restart: false,+ startSource: null,supervision: {links: null,build: consoleSupervision.build,diff --git a/console/apps/switch-console-desktop/src/main/core/sdk-host/shared-agent-runtime.initial-prompt.test.ts b/console/apps/switch-console-desktop/src/main/core/sdk-host/shared-agent-runtime.initial-prompt.test.tsindex 8603f44e0..8945e499f 100644--- a/console/apps/switch-console-desktop/src/main/core/sdk-host/shared-agent-runtime.initial-prompt.test.ts+++ b/console/apps/switch-console-desktop/src/main/core/sdk-host/shared-agent-runtime.initial-prompt.test.ts@@ -19,6 +19,7 @@ const mocks = vi.hoisted(() => ({definition: vi.fn(),behavior: {} as Record<string, unknown>,ready: vi.fn(),+ sidecarEnsure: vi.fn(),}));vi.mock('@main/core/managed-switch-server/session-readiness', () => ({@@ -27,7 +28,11 @@ vi.mock('@main/core/managed-switch-server/session-readiness', () => ({vi.mock('./transcripts', () => ({ currentSnapshot: mocks.snapshot }));vi.mock('./host-journal', () => ({ JournalUnavailableError: class extends Error {} }));-vi.mock('./sidecar-control', () => ({ withSidecar: vi.fn() }));+vi.mock('./sidecar-control', () => ({+ withSidecar: async (_agentId: string, act: (client: unknown) => Promise<unknown>) =>+ act({ ensure: mocks.sidecarEnsure }),+}));+vi.mock('./legacy-sidecar', () => ({ stopLegacySidecar: vi.fn() }));vi.mock('@switch-console/shared/session-v1', async (importOriginal) => ({...(await importOriginal<object>()),snapshotSchema: { parse: (value: unknown) => value },@@ -158,6 +163,39 @@ it('delivers the initial prompt on a relaunch that did not create the host', asyexpect(mocks.persist.mock.calls.map((call) => call[1].state)).toEqual(['pending', 'submitted']);});+it('hands the host how a new session started, so it can tell Switch', async () => {+ await runtime().start(session, false, 'Say hello', 'user');++ expect(mocks.runHost).toHaveBeenCalledWith(expect.any(String), expect.anything(), {+ resuming: false,+ restart: false,+ startSource: 'user',+ });+});++it('hands a remote host how a new session started, beside its config', async () => {+ const agent = new SharedAgentRuntime(+ { kind: 'ssh', connectionId: 'host-1' } as LocationTransport,+ { sessionId: session.id, sessionPath: '/work', sessionEnvVars: {} }+ );++ await agent.start(session, false, 'Say hello', 'user');++ expect(mocks.runHost).not.toHaveBeenCalled();+ expect(mocks.sidecarEnsure).toHaveBeenCalledWith(+ expect.objectContaining({ resuming: false, restart: false, startSource: 'user' })+ );+ // Beside the config, never in it: an older sidecar refuses a config key it+ // does not know, and would refuse the session with it.+ expect(mocks.sidecarEnsure.mock.calls[0][0].config).not.toHaveProperty('startSource');+});++it('hands the host no start source for a caller that gave none', async () => {+ await runtime().start(session, true);++ expect(mocks.runHost.mock.calls[0][2]).toMatchObject({ startSource: null });+});+it('accepts a host that awaits an explicit reset decision and holds the initial prompt', async () => {mocks.snapshot.mockResolvedValue({session: {diff --git a/console/apps/switch-console-desktop/src/main/core/sdk-host/shared-agent-runtime.ts b/console/apps/switch-console-desktop/src/main/core/sdk-host/shared-agent-runtime.tsindex 89fb92b33..a63e43c81 100644--- a/console/apps/switch-console-desktop/src/main/core/sdk-host/shared-agent-runtime.ts+++ b/console/apps/switch-console-desktop/src/main/core/sdk-host/shared-agent-runtime.ts@@ -17,6 +17,7 @@ import { join, posix } from 'node:path';import { setTimeout as delay } from 'node:timers/promises';import {agentLaunchDefinitionSchema,+ type HostStartSource,SessionHostFailedError,sharedConfigSchema,sharedSessionRoot,@@ -102,7 +103,12 @@ export class SharedAgentRuntime implements AgentRuntimeProvider {announceSessionIssue(this.params.sessionId);}- async start(session: Session, isResuming?: boolean, initialPrompt?: string): Promise<void> {+ async start(+ session: Session,+ isResuming?: boolean,+ initialPrompt?: string,+ startSource: HostStartSource | null = null+ ): Promise<void> {if (this.starting) return this.opened ?? this.starting;this.setStartupError(null);let connected!: () => void;@@ -111,7 +117,14 @@ export class SharedAgentRuntime implements AgentRuntimeProvider {connected = resolve;failed = reject;});- this.starting = this.open(session, initialPrompt, isResuming ?? false, false, connected);+ this.starting = this.open(+ session,+ initialPrompt,+ isResuming ?? false,+ false,+ startSource,+ connected+ );void this.starting.then(connected, (error: unknown) => {this.setStartupError(error instanceof Error ? error.message : String(error));@@ -132,6 +145,7 @@ export class SharedAgentRuntime implements AgentRuntimeProvider {initialPrompt: string | undefined,isResuming: boolean,restart: boolean,+ startSource: HostStartSource | null,connected: () => void): Promise<void> {this.startupStage = 'Preparing the session on its host…';@@ -176,13 +190,13 @@ export class SharedAgentRuntime implements AgentRuntimeProvider {// Started by the agent's sidecar, which is then its parent: it talks to// the session over IPC, and Console reaches it through the sidecar.await withSidecar(session.agentId, (client) =>- client.ensure({ config, resuming: isResuming, restart })+ client.ensure({ config, resuming: isResuming, restart, startSource }));} else {// A local session is supervised by Console, so it ends when Console does.root = sharedSessionRoot(session.id);readFailure = () => readLocalHostFailure(root);- await startLocalSession(root, config, { resuming: isResuming, restart });+ await startLocalSession(root, config, { resuming: isResuming, restart, startSource });}this.startupStage = 'Connecting to the session host…';let roomBound = false;@@ -342,7 +356,7 @@ export class SharedAgentRuntime implements AgentRuntimeProvider {await this.resolveServer();if (this.starting) await this.starting;this.setStartupError(null);- this.starting = this.open(session, undefined, true, true, () => {});+ this.starting = this.open(session, undefined, true, true, null, () => {});try {await this.starting;} catch (error) {diff --git a/console/apps/switch-console-desktop/src/main/core/sessions/operations/createSession.test.ts b/console/apps/switch-console-desktop/src/main/core/sessions/operations/createSession.test.tsindex d1dc63c0a..443c4ef9c 100644--- a/console/apps/switch-console-desktop/src/main/core/sessions/operations/createSession.test.ts+++ b/console/apps/switch-console-desktop/src/main/core/sessions/operations/createSession.test.ts@@ -119,10 +119,25 @@ describe('createSession', () => {expect(mocks.startSession).toHaveBeenCalledWith(expect.not.objectContaining({ autoApprove: stale }),false,- undefined+ undefined,+ null);});+ it.each([+ ['user', 'user'],+ ['auto', 'automation'],+ ['unknown', null],+ [undefined, null],+ ] as const)(+ 'tells the host a session started by %s was started by %s',+ async (startSource, reported) => {+ const result = await createSession({ ...baseParams, startSource });+ expect(result.success).toBe(true);+ expect(mocks.startSession.mock.calls[0]![3]).toBe(reported);+ }+ );+it('adopts a session at a closed location without provisioning or launching it', async () => {mocks.getLocation.mockReturnValue(undefined);const result = await createSession({ ...baseParams, startSource: 'adopted', attach: false });diff --git a/console/apps/switch-console-desktop/src/main/core/sessions/operations/createSession.ts b/console/apps/switch-console-desktop/src/main/core/sessions/operations/createSession.tsindex 8aa371ea6..276646386 100644--- a/console/apps/switch-console-desktop/src/main/core/sessions/operations/createSession.ts+++ b/console/apps/switch-console-desktop/src/main/core/sessions/operations/createSession.ts@@ -1,3 +1,4 @@+import type { HostStartSource } from '@switch-console/agent-providers';import { err, ok, type Result } from '@switch-console/shared';import { eq, sql } from 'drizzle-orm';import { providerAdapterRegistry } from '@main/core/agent-runtime/impl/provider-adapter-registry';@@ -11,10 +12,22 @@ import type {CreateSessionSuccess,CreateSessionParams,} from '@shared/core/sessions/sessions';+import type { SessionStartSource } from '@shared/core/telemetry/reporting';import { provisionSessionRuntime } from '../session-builder';import { sessionRuntimeManager } from '../session-runtime-manager';import { mapSessionRowToSession } from '../utils/utils';+/**+ * What the session's host tells Switch about how it started. `adopted` never+ * gets here with a launch, and a caller that said nothing is reported as+ * `unknown` by the host rather than guessed at.+ */+function hostStartSource(source: SessionStartSource | undefined): HostStartSource | null {+ if (source === 'user') return 'user';+ if (source === 'auto') return 'automation';+ return null;+}+export async function createSession(params: CreateSessionParams): Promise<Result<CreateSessionSuccess, CreateSessionError>> {@@ -72,7 +85,12 @@ export async function createSession(const built = await provisionSessionRuntime(session, location);await sessionRuntimeManager.registerSession(session.id, built, location.ctx);- await built.agent.start(session, params.attach === false, params.initialPrompt);+ await built.agent.start(+ session,+ params.attach === false,+ params.initialPrompt,+ hostStartSource(params.startSource)+ );} catch (e) {await db.update(sessions).set({ status: 'review' }).where(eq(sessions.id, session.id));return err({ type: 'spawn-failed', message: e instanceof Error ? e.message : String(e) });diff --git a/console/apps/switch-console-desktop/src/renderer/features/sessions/stores/session-manager.test.ts b/console/apps/switch-console-desktop/src/renderer/features/sessions/stores/session-manager.test.tsindex 20011b558..382ee67e9 100644--- a/console/apps/switch-console-desktop/src/renderer/features/sessions/stores/session-manager.test.ts+++ b/console/apps/switch-console-desktop/src/renderer/features/sessions/stores/session-manager.test.ts@@ -12,6 +12,8 @@ type MockViewModel = {const mocks = vi.hoisted(() => ({archiveSession: vi.fn(),+ createSession: vi.fn(),+ getAgentById: vi.fn(),agentAcquire: vi.fn(),agentRelease: vi.fn(),getLocationManagerStore: vi.fn(),@@ -33,10 +35,11 @@ vi.mock('@renderer/lib/ipc', () => ({},rpc: {agents: {- getAgentById: vi.fn(),+ getAgentById: mocks.getAgentById,},sessions: {archiveSession: mocks.archiveSession,+ createSession: mocks.createSession,getSessions: mocks.getSessions,provisionSession: mocks.provisionSession,teardownSession: mocks.teardownSession,@@ -244,3 +247,33 @@ describe('SessionManagerStore discardFailedCreations', () => {manager.dispose();});});++describe('SessionManagerStore creating a session', () => {+ beforeEach(() => {+ vi.clearAllMocks();+ mocks.getAgentById.mockResolvedValue({ id: 'agent-1', providerId: 'claude' });+ mocks.agentAcquire.mockReturnValue({ agent: null });+ mocks.createSession.mockImplementation(async (params: { id: string }) => ({+ success: true,+ data: { session: makeSession({ id: params.id }) },+ }));+ mocks.getLocationManagerStore.mockReturnValue({ mountLocation: mocks.mountLocation });+ mocks.mountLocation.mockResolvedValue(undefined);+ mocks.provisionSession.mockResolvedValue({+ success: true,+ data: { path: '/tmp/location-1', locationId: 'location-1' },+ });+ });++ it('says a person started it, which is the only way this interface starts one', async () => {+ await makeSessionManager().createSession({+ id: 'session-2',+ agentId: 'agent-1',+ title: 'Session 2',+ });++ expect(mocks.createSession).toHaveBeenCalledWith(+ expect.objectContaining({ id: 'session-2', startSource: 'user' })+ );+ });+});diff --git a/console/apps/switch-console-desktop/src/renderer/features/sessions/stores/session-manager.ts b/console/apps/switch-console-desktop/src/renderer/features/sessions/stores/session-manager.tsindex 844938bf4..df04d045c 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@@ -231,8 +231,13 @@ export class SessionManagerStore {}});+ // A session this interface creates is a person pressing something: the+ // automation API and adoption start theirs in the main process, never+ // through here. Reported by this app's telemetry and, by the session's+ // host, to Switch.+ const request: CreateSessionParams = { ...toJS(params), startSource: 'user' };const result = await rpc.sessions- .createSession(JSON.parse(JSON.stringify(toJS(params))) as typeof params)+ .createSession(JSON.parse(JSON.stringify(request)) as typeof params).catch((e: unknown) => {const message = failureText(e, 'Could not create the session.');clearOptimisticInitialWorking();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.tsindex 28818c838..40dbfa65e 100644--- a/console/apps/switch-console-desktop/src/shared/core/telemetry/reporting.ts+++ b/console/apps/switch-console-desktop/src/shared/core/telemetry/reporting.ts@@ -35,18 +35,18 @@ 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.+ * `user` is a person pressing something in this app. `auto` is a session started+ * through the app's local automation API, with nobody at the desktop app.+ * `adopted` is a session the app discovered on a host rather than started —+ * including one the room watcher started because the agent was addressed in a+ * room. `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.+ * adopt and report the same session. Room-started sessions arrive as `adopted`+ * for that reason, and only while the app is running; the Switch server's own+ * `session_started`, reported by each session's host, counts them directly.*/export const SESSION_START_SOURCES = ['user', 'auto', 'adopted', 'unknown'] as const;diff --git a/console/packages/agent-providers/src/host/bench/daemon.ts b/console/packages/agent-providers/src/host/bench/daemon.tsindex b8b7f29f5..42b14ca40 100644--- a/console/packages/agent-providers/src/host/bench/daemon.ts+++ b/console/packages/agent-providers/src/host/bench/daemon.ts@@ -23,13 +23,8 @@import { spawn } from 'node:child_process';import { mkdir, readFile } from 'node:fs/promises';import { join, resolve } from 'node:path';-import { type EnsureSession, serveControl } from '../control';-import {- detachedSupervision,- ensureSharedProcess,- inProcessSupervision,- sharedSessionRoot,-} from '../launch';+import { ensureSessions, serveControl } from '../control';+import { detachedSupervision, ensureSharedProcess, inProcessSupervision } from '../launch';import { replaceOwner } from '../ownership-lock';import { ownProcessGroup } from '../process-fence';import { SessionLinks } from '../session-channel';@@ -56,6 +51,7 @@ async function main(): Promise<void> {watcher: mode === '--ensure-watch',restart: false,supervision: detachedSupervision(process.argv[1]!),+ startSource: null,})));@@ -84,17 +80,7 @@ async function main(): Promise<void> {// As the shipped sidecar does: its sessions are its children, over IPC.const links = new SessionLinks();const supervision = inProcessSupervision(process.argv[1]!, links);- const ensure: EnsureSession = async (input) => {- const session = sharedConfigSchema.parse(input.config);- return ensureSharedProcess({- root: sharedSessionRoot(session.session.sessionId),- config: session,- resuming: input.resuming,- watcher: false,- restart: input.restart,- supervision,- });- };+ const ensure = ensureSessions(supervision);// Console's "Reconnect to room" reaches the watcher through the control port.const control = new WatcherControl();// A watcher that stops (disabled, stood down after a takeover, ordiff --git a/console/packages/agent-providers/src/host/control.test.ts b/console/packages/agent-providers/src/host/control.test.tsindex 7dbf249ca..5de334a99 100644--- a/console/packages/agent-providers/src/host/control.test.ts+++ b/console/packages/agent-providers/src/host/control.test.ts@@ -5,12 +5,15 @@ import { connect } from 'node:net';import { tmpdir } from 'node:os';import { join } from 'node:path';import { afterEach, expect, it, vi } from 'vitest';-import { CONTROL_FILE, ControlClient, serveControl } from './control';+import { CONTROL_FILE, ControlClient, ensureSessions, serveControl } from './control';+import type { Supervision } from './launch';import { SessionHostFailedError, SessionLinks } from './session-channel';import { WatcherControl } from './watcher-tools';const paths = vi.hoisted(() => ({ base: '' }));+const launched = vi.hoisted(() => ({ ensureSharedProcess: vi.fn() }));vi.mock('./launch', () => ({+ ensureSharedProcess: launched.ensureSharedProcess,sharedSessionRoot: (id: string) => join(paths.base, id),liveSupervisor: async (root: string) =>(await readFile(join(root, 'running'), 'utf8').catch(() => null)) ? { build: 'b' } : null,@@ -64,7 +67,7 @@ async function started() {const socket = connect(control.port, '127.0.0.1');return new ControlClient(socket, token);};- return { base, links, ensure, stop, serving, client, watcher };+ return { base, links, ensure, stop, serving, client, watcher, control };}it('relays requests to a session host and its events back', async () => {@@ -90,10 +93,17 @@ it('relays requests to a session host and its events back', async () => {await vi.waitFor(() => expect(heard).toEqual([1]));unsubscribe();- expect(await console.ensure({ config: {}, resuming: false, restart: false })).toEqual({+ expect(+ await console.ensure({ config: {}, resuming: false, restart: false, startSource: 'room' })+ ).toEqual({created: true,});- expect(ensure).toHaveBeenCalledWith({ config: {}, resuming: false, restart: false });+ expect(ensure).toHaveBeenCalledWith({+ config: {},+ resuming: false,+ restart: false,+ startSource: 'room',+ });console.close();stop.abort();@@ -249,3 +259,153 @@ it('answers the watcher health and pushes every change to a client watching it',stop.abort();await serving;});++it('still starts a session for a Console that sends no start source', async () => {+ // What a Console older than start sources writes: the same message, one key short.+ const { ensure, stop, serving, control } = await started();+ const socket = connect(control.port, '127.0.0.1');+ const replies: unknown[] = [];+ let buffered = '';+ socket.on('data', (chunk: Buffer) => {+ buffered += chunk.toString();+ let end: number;+ while ((end = buffered.indexOf('\n')) >= 0) {+ replies.push(JSON.parse(buffered.slice(0, end)));+ buffered = buffered.slice(end + 1);+ }+ });+ socket.write(`${JSON.stringify({ token: control.token })}\n`);+ socket.write(+ `${JSON.stringify({ id: 1, ensure: { config: {}, resuming: false, restart: false } })}\n`+ );++ await vi.waitFor(() =>+ expect(replies).toContainEqual({ id: 1, ok: true, value: { created: true } })+ );+ expect(ensure).toHaveBeenCalledWith({ config: {}, resuming: false, restart: false });++ socket.destroy();+ stop.abort();+ await serving;+});++const sessionConfig = {+ session: {+ sessionId: 'session-1',+ agentId: 'agent',+ hostId: 'host',+ epoch: 'initial',+ provider: 'codex',+ status: 'starting',+ connectivity: 'online',+ pendingRequestIds: [],+ capabilities: {+ input: 'queue',+ approvals: true,+ questions: true,+ interrupt: true,+ reset: false,+ compact: false,+ modelChange: false,+ attachmentMimeTypes: [],+ },+ },+ start: {+ provider: 'codex',+ input: {+ sessionId: 'session-1',+ cwd: '/work',+ runtimeMode: 'approval-required',+ env: {},+ mcpServers: {},+ },+ },+};++it('starts the session a sidecar is asked for with the start source it was given', async () => {+ paths.base = '/sessions';+ launched.ensureSharedProcess.mockReset().mockResolvedValue({ created: true });+ const supervision = { build: 'b' } as unknown as Supervision;++ await ensureSessions(supervision)({+ config: sessionConfig,+ resuming: false,+ restart: false,+ startSource: 'room',+ });++ expect(launched.ensureSharedProcess).toHaveBeenCalledWith(+ expect.objectContaining({+ root: join('/sessions', 'session-1'),+ watcher: false,+ supervision,+ startSource: 'room',+ })+ );+});++it('records a start source an older Console did not send as not known', async () => {+ launched.ensureSharedProcess.mockReset().mockResolvedValue({ created: true });++ await ensureSessions({ build: 'b' } as unknown as Supervision)({+ config: sessionConfig,+ resuming: false,+ restart: false,+ });++ expect(launched.ensureSharedProcess.mock.calls[0]![0]).toMatchObject({ startSource: null });+});++it('carries a start source Console could not name as null, which a resume always does', async () => {+ const { ensure, stop, serving, client } = await started();+ const console = client();+ await console.ready;++ await console.ensure({ config: {}, resuming: true, restart: false, startSource: null });++ expect(ensure).toHaveBeenCalledWith({+ config: {},+ resuming: true,+ restart: false,+ startSource: null,+ });+ console.close();+ stop.abort();+ await serving;+});++it('starts a session whose start source is newer than this sidecar, as not known', async () => {+ const { ensure, stop, serving, control } = await started();+ const socket = connect(control.port, '127.0.0.1');+ const replies: unknown[] = [];+ let buffered = '';+ socket.on('data', (chunk: Buffer) => {+ buffered += chunk.toString();+ let end: number;+ while ((end = buffered.indexOf('\n')) >= 0) {+ replies.push(JSON.parse(buffered.slice(0, end)));+ buffered = buffered.slice(end + 1);+ }+ });+ socket.write(`${JSON.stringify({ token: control.token })}\n`);+ socket.write(+ `${JSON.stringify({+ id: 1,+ ensure: { config: {}, resuming: false, restart: false, startSource: 'scheduled' },+ })}\n`+ );++ await vi.waitFor(() =>+ expect(replies).toContainEqual({ id: 1, ok: true, value: { created: true } })+ );+ expect(ensure).toHaveBeenCalledWith({+ config: {},+ resuming: false,+ restart: false,+ startSource: null,+ });++ socket.destroy();+ stop.abort();+ await serving;+});diff --git a/console/packages/agent-providers/src/host/control.ts b/console/packages/agent-providers/src/host/control.tsindex 94854d5c5..04092ea67 100644--- a/console/packages/agent-providers/src/host/control.ts+++ b/console/packages/agent-providers/src/host/control.ts@@ -5,7 +5,7 @@ import { join } from 'node:path';import type { Duplex } from 'node:stream';import { serverEventSchema, type ServerEvent } from '@switch-console/shared/session-v1';import { z } from 'zod';-import { liveSupervisor, sharedSessionRoot } from './launch';+import { ensureSharedProcess, liveSupervisor, sharedSessionRoot, type Supervision } from './launch';import {SessionHostFailedError,sessionRequestSchema,@@ -13,6 +13,8 @@ import {type SessionLinks,type SessionRequest,} from './session-channel';+import { hostStartSources, type HostStartSource } from './session-start';+import { sharedConfigSchema } from './shared-config';import {type PlaceOutcome,type WatcherControl,@@ -39,7 +41,17 @@ const clientMessageSchema = z.union([z.object({ id: z.number().int(), unsubscribe: z.string().min(1) }),z.object({id: z.number().int(),- ensure: z.object({ config: z.unknown(), resuming: z.boolean(), restart: z.boolean() }),+ ensure: z.object({+ config: z.unknown(),+ resuming: z.boolean(),+ restart: z.boolean(),+ // Beside the config rather than in it: a sidecar older than Console+ // parses the config strictly and would refuse the session over a key it+ // does not know, but drops one here. Absent from an older Console, and+ // a source newer than this sidecar reads as not known rather than+ // refusing the session.+ startSource: z.enum(hostStartSources).nullable().optional().catch(null),+ }),}),/** Console's "Reconnect to room": move a room's messages to this session. */z.object({@@ -60,8 +72,29 @@ export type EnsureSession = (input: {config: unknown;resuming: boolean;restart: boolean;+ startSource?: HostStartSource | null;}) => Promise<unknown>;+/**+ * How a sidecar answers `ensure`: start the session the message names, or+ * reattach to it, under `supervision`. A message from a Console that predates+ * start sources carries none, which is recorded as not known.+ */+export function ensureSessions(supervision: Supervision): EnsureSession {+ return async (input) => {+ const config = sharedConfigSchema.parse(input.config);+ return ensureSharedProcess({+ root: sharedSessionRoot(config.session.sessionId),+ config,+ resuming: input.resuming,+ watcher: false,+ restart: input.restart,+ supervision,+ startSource: input.startSource ?? null,+ });+ };+}+/** How long a request waits for the session's host to be ready. */const REQUEST_WAIT_MS = 30000;@@ -315,7 +348,12 @@ export class ControlClient {return this.call({ sessionId, request });}- ensure(input: { config: unknown; resuming: boolean; restart: boolean }): Promise<unknown> {+ ensure(input: {+ config: unknown;+ resuming: boolean;+ restart: boolean;+ startSource: HostStartSource | null;+ }): Promise<unknown> {return this.call({ ensure: input });}diff --git a/console/packages/agent-providers/src/host/launch.test.ts b/console/packages/agent-providers/src/host/launch.test.tsindex 42f1b6bc4..aee5a5658 100644--- a/console/packages/agent-providers/src/host/launch.test.ts+++ b/console/packages/agent-providers/src/host/launch.test.ts@@ -1,11 +1,12 @@import { spawn } from 'node:child_process';import { once } from 'node:events';-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';+import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises';import { tmpdir } from 'node:os';import { join } from 'node:path';import { afterEach, expect, it, vi } from 'vitest';import { detachedSupervision, ensureSharedProcess, inProcessSupervision } from './launch';import { SessionLinks } from './session-channel';+import { owedSessionStart, type HostStartSource } from './session-start';import type { SharedHostConfig } from './shared-config';const roots: string[] = [];@@ -56,6 +57,7 @@ async function fixture() {watcher: false,restart: true,supervision: detachedSupervision(entrypoint),+ startSource: null as HostStartSource | null,};}it('refuses to replace missing conversation state with a fresh session', async () => {@@ -224,3 +226,83 @@ it('stops the hosts it supervises in-process when closed, and starts no more', asupervision.start({ root, configPath: join(root, 'config.json'), watcher: false })).rejects.toThrow('shutting down');});++/** Launches that start nothing, so what is written to the root can be read. */+const inert = {+ build: 'test',+ links: null,+ start: async () => {},+ stop: async () => {},+};++it('records how a session started when the launch creates it', async () => {+ const input = await fixture();+ await ensureSharedProcess({+ ...input,+ resuming: false,+ restart: false,+ supervision: inert,+ startSource: 'user',+ });++ expect(await owedSessionStart(input.root)).toBe('user');+});++it('records a launcher that said nothing as unknown rather than not at all', async () => {+ const input = await fixture();+ await ensureSharedProcess({ ...input, resuming: false, restart: false, supervision: inert });++ expect(await owedSessionStart(input.root)).toBe('unknown');+});++it('records nothing for a session that already existed', async () => {+ const input = await fixture();+ await writeFile(join(input.root, 'config.json'), JSON.stringify(input.config));+ await ensureSharedProcess({+ ...input,+ resuming: false,+ restart: false,+ supervision: inert,+ startSource: 'room',+ });++ expect(await owedSessionStart(input.root)).toBeNull();+});++it('records nothing for a watcher, which is not a session', async () => {+ const input = await fixture();+ await ensureSharedProcess({+ ...input,+ resuming: false,+ restart: false,+ watcher: true,+ supervision: inert,+ startSource: 'room',+ });++ expect(await owedSessionStart(input.root)).toBeNull();+});++it('starts the session anyway when its start cannot be recorded', async () => {+ const input = await fixture();+ // Something in the way of the record: here, a directory where the file goes.+ await mkdir(join(input.root, 'session-start.json'));+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const started = vi.fn(async () => {});++ await ensureSharedProcess({+ ...input,+ resuming: false,+ restart: false,+ supervision: { ...inert, start: started },+ startSource: 'user',+ });++ expect(started).toHaveBeenCalledOnce();+ expect(warn).toHaveBeenCalledWith(expect.stringContaining('Could not record how session'));+ // And leaves nothing half-written behind.+ expect(+ (await readdir(input.root)).filter((name) => name.includes('session-start.json.'))+ ).toEqual([]);+ warn.mockRestore();+});diff --git a/console/packages/agent-providers/src/host/launch.ts b/console/packages/agent-providers/src/host/launch.tsindex 05fb598b6..7c667453c 100644--- a/console/packages/agent-providers/src/host/launch.ts+++ b/console/packages/agent-providers/src/host/launch.ts@@ -7,6 +7,7 @@ import { setTimeout as delay } from 'node:timers/promises';import { promisify } from 'node:util';import { replaceOwner, withOwnershipLock } from './ownership-lock';import type { SessionLinks } from './session-channel';+import { recordSessionStart, type HostStartSource } from './session-start';import { sharedConfigSchema, type SharedHostConfig } from './shared-config';import { superviseSharedHost } from './supervisor';@@ -49,6 +50,12 @@ type LaunchInput = {watcher: boolean;restart: boolean;supervision: Supervision;+ /**+ * How the session came to start, recorded only when this launch creates+ * its state root. Null when the caller cannot say; it is reported as+ * `unknown` rather than not at all.+ */+ startSource: HostStartSource | null;};export function detachedSupervision(entrypoint: string): Supervision {@@ -172,6 +179,15 @@ async function launch(input: LaunchInput): Promise<{ created: boolean }> {} finally {await unlink(temporary);}+ // Only the launch that created the root: every later one — a resume, a+ // restart, a relaunch after parking — is the same session going on. A+ // record that cannot be written costs the report, never the session.+ if (created && !input.watcher)+ await recordSessionStart(input.root, input.startSource).catch((error: unknown) => {+ console.warn(+ `Could not record how session ${input.config.session.sessionId} started, so it is not reported: ${String(error)}`+ );+ });if (process.platform !== 'win32') {const directory = await open(input.root, 'r');try {diff --git a/console/packages/agent-providers/src/host/session-start.ts b/console/packages/agent-providers/src/host/session-start.tsnew file mode 100644index 000000000..e4f7168e7--- /dev/null+++ b/console/packages/agent-providers/src/host/session-start.ts@@ -0,0 +1,76 @@+import { randomUUID } from 'node:crypto';+import { open, readFile, rename, unlink } from 'node:fs/promises';+import { join } from 'node:path';+import { z } from 'zod';++/**+ * How a session came to start, as whatever launched it knows: a person in+ * Console (`user`), the agent being addressed in a room (`room`), or Console's+ * local automation API (`automation`).+ *+ * Only the launcher knows this. Sessions share their agent's one connection to+ * Switch, so nothing about a new session reaches the server unless its host+ * says so — which it does once, from what the launcher recorded here.+ */+export const hostStartSources = ['user', 'room', 'automation'] as const;+export type HostStartSource = (typeof hostStartSources)[number];++/**+ * Written beside `config.json` when a state root is created, and removed once+ * the server has answered the report.+ *+ * A file of its own rather than a field on the config: the config is parsed+ * strictly by every build that reads it, including an older sidecar on a+ * remote host, so a new field there would make that sidecar refuse to start+ * the session. No older build reads this file.+ */+export const SESSION_START_FILE = 'session-start.json';++// `unknown` is a launcher that said nothing — an older Console asking a newer+// sidecar, say. Reported rather than dropped, so a launch path nobody stamped+// shows up as a gap instead of as no sessions.+const owedSchema = z.strictObject({+ startSource: z.enum([...hostStartSources, 'unknown']),+});+export type OwedSessionStart = z.infer<typeof owedSchema>['startSource'];++/** Records that this new session's start is owed to the server. */+export async function recordSessionStart(+ root: string,+ startSource: HostStartSource | null+): Promise<void> {+ const path = join(root, SESSION_START_FILE);+ const temporary = `${path}.${randomUUID()}`;+ const file = await open(temporary, 'wx', 0o600);+ try {+ await file.writeFile(JSON.stringify({ startSource: startSource ?? 'unknown' }));+ await file.sync();+ } finally {+ await file.close();+ }+ try {+ await rename(temporary, path);+ } catch (error) {+ await unlink(temporary).catch(() => {});+ throw error;+ }+}++/** The start this session still owes the server, or null if it owes none. */+export async function owedSessionStart(root: string): Promise<OwedSessionStart | null> {+ let text: string;+ try {+ text = await readFile(join(root, SESSION_START_FILE), 'utf8');+ } catch (error) {+ if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;+ throw error;+ }+ return owedSchema.parse(JSON.parse(text)).startSource;+}++/** The server answered, so the start is no longer owed. */+export async function settleSessionStart(root: string): Promise<void> {+ await unlink(join(root, SESSION_START_FILE)).catch((error: NodeJS.ErrnoException) => {+ if (error.code !== 'ENOENT') throw error;+ });+}diff --git a/console/packages/agent-providers/src/host/shared-daemon.ts b/console/packages/agent-providers/src/host/shared-daemon.tsindex 17a06dc0b..fe9119731 100644--- a/console/packages/agent-providers/src/host/shared-daemon.ts+++ b/console/packages/agent-providers/src/host/shared-daemon.ts@@ -2,13 +2,8 @@ import { spawn } from 'node:child_process';import { randomUUID } from 'node:crypto';import { mkdir, readFile } from 'node:fs/promises';import { join, resolve } from 'node:path';-import { type EnsureSession, serveControl } from './control';-import {- detachedSupervision,- ensureSharedProcess,- inProcessSupervision,- sharedSessionRoot,-} from './launch';+import { ensureSessions, serveControl } from './control';+import { detachedSupervision, ensureSharedProcess, inProcessSupervision } from './launch';import { replaceOwner } from './ownership-lock';import { ownProcessGroup } from './process-fence';import { checkProviderReadiness } from './provider-readiness';@@ -92,6 +87,7 @@ async function main(): Promise<void> {watcher: mode === '--ensure-watch',restart: mode === '--restart',supervision: detachedSupervision(process.argv[1]!),+ startSource: null,})));@@ -121,17 +117,7 @@ async function main(): Promise<void> {// IPC, and Console reaches them through its control port.const links = new SessionLinks();const supervision = inProcessSupervision(process.argv[1]!, links);- const ensure: EnsureSession = async (input) => {- const session = sharedConfigSchema.parse(input.config);- return ensureSharedProcess({- root: sharedSessionRoot(session.session.sessionId),- config: session,- resuming: input.resuming,- watcher: false,- restart: input.restart,- supervision,- });- };+ const ensure = ensureSessions(supervision);// Console's "Reconnect to room" reaches the watcher through the control port.const control = new WatcherControl();// A watcher that stops (disabled, stood down after a takeover, ordiff --git a/console/packages/agent-providers/src/host/shared-host.test.ts b/console/packages/agent-providers/src/host/shared-host.test.tsindex f860922c5..d5d9654e8 100644--- a/console/packages/agent-providers/src/host/shared-host.test.ts+++ b/console/packages/agent-providers/src/host/shared-host.test.ts@@ -1,6 +1,6 @@import { createHash, randomUUID } from 'node:crypto';import { EventEmitter } from 'node:events';-import { mkdtemp, readFile, rm } from 'node:fs/promises';+import { access, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';import { tmpdir } from 'node:os';import { join } from 'node:path';import type { Command, Session } from '@switch-console/shared/session-v1';@@ -95,12 +95,28 @@ async function start(ask?: 'approval' | 'questions';parkAfterMs?: number;resettable?: boolean;+ /** What the launcher recorded when it created this session's root, if it did. */+ owedStart?: string;+ /** The file's text as written, for one that is not what a launcher writes. */+ owedStartText?: string;+ /** Something the host can neither read nor remove where the record goes. */+ owedStartBlocked?: boolean;+ startUnknown?: boolean;+ startRefused?: boolean;+ unavailable?: boolean;} = {}): Promise<Harness> {const parent = fakeParent();const base = await mkdtemp(join(tmpdir(), 'shared-host-test-'));roots.push(base);const root = join(base, 'session');+ const owedText =+ opts.owedStartText ?? (opts.owedStart ? JSON.stringify({ startSource: opts.owedStart }) : null);+ if (opts.owedStartBlocked) await mkdir(join(root, 'session-start.json'), { recursive: true });+ if (owedText !== null) {+ await mkdir(root, { recursive: true });+ await writeFile(join(root, 'session-start.json'), owedText);+ }const stop = new AbortController();const turns: Harness['turns'] = [];let listener: (event: ProviderRuntimeEvent) => void = () => {};@@ -189,6 +205,9 @@ async function start(return new Response('not a route this host should call', { status: 599 });}));+ switchCore.state.startUnknown = opts.startUnknown ?? false;+ switchCore.state.startRefused = opts.startRefused ?? false;+ switchCore.state.unavailable = opts.unavailable ?? false;const session = structuredClone(SESSION);if (opts.rooms) session.capabilities.attachmentMimeTypes = ['text/plain'];if (opts.resettable) session.capabilities.reset = true;@@ -756,3 +775,132 @@ it('tells the session to rejoin its room once a reset asked for there has applieexpect(await host.stop()).toBeNull();}}, 20000);++const startReports = (host: Harness) =>+ host.switchCore.calls.filter((c) => c.path.endsWith('/started'));+const owed = (host: Harness) =>+ access(join(host.root, 'session-start.json')).then(+ () => true,+ () => false+ );++it('tells Switch once how a new session started, then owes it nothing', async () => {+ const host = await start({ owedStart: 'room' });+ try {+ await vi.waitFor(() => expect(startReports(host)).toHaveLength(1), { timeout: 5000 });+ expect(startReports(host)[0]).toEqual({+ method: 'POST',+ path: '/agent/agent-sessions/session/started',+ body: { start_source: 'room' },+ });+ await vi.waitFor(async () => expect(await owed(host)).toBe(false), { timeout: 3000 });+ } finally {+ expect(await host.stop()).toBeNull();+ }+});++it('says nothing about starting for a session its launcher did not create', async () => {+ const host = await start();+ try {+ // The reporting loop has gone round at least once.+ await vi.waitFor(+ () =>+ expect(host.switchCore.calls.some((c) => c.path.endsWith('/approvals/outcomes'))).toBe(+ true+ ),+ { timeout: 5000 }+ );+ expect(startReports(host)).toEqual([]);+ } finally {+ expect(await host.stop()).toBeNull();+ }+});++it('keeps reporting activity to a server that predates start reports', async () => {+ const host = await start({ rooms: true, owedStart: 'user', startUnknown: true });+ try {+ await vi.waitFor(() => expect(startReports(host)).toHaveLength(1), { timeout: 5000 });+ await vi.waitFor(async () => expect(await owed(host)).toBe(false), { timeout: 3000 });+ await host.parent.ask({ type: 'room', handoff: roomMessage(1, 'Carry on') });+ await vi.waitFor(+ () => expect(host.switchCore.calls.some((c) => c.path.endsWith('/activity'))).toBe(true),+ { timeout: 5000 }+ );+ } finally {+ expect(await host.stop()).toBeNull();+ }+}, 20000);++it('keeps a start owed while Switch is unreachable, and reports it once Switch answers', async () => {+ const host = await start({ owedStart: 'automation', unavailable: true });+ try {+ await vi.waitFor(() => expect(startReports(host).length).toBeGreaterThan(0), {+ timeout: 5000,+ });+ expect(await owed(host)).toBe(true);+ host.switchCore.state.unavailable = false;+ await vi.waitFor(async () => expect(await owed(host)).toBe(false), { timeout: 5000 });+ expect(startReports(host).at(-1)!.body).toEqual({ start_source: 'automation' });+ } finally {+ expect(await host.stop()).toBeNull();+ }+});++it('still owes a start its host was stopped before Switch answered', async () => {+ // The next time the session's host runs, it reports it then.+ const host = await start({ owedStart: 'user', unavailable: true });+ await vi.waitFor(() => expect(startReports(host).length).toBeGreaterThan(0), {+ timeout: 5000,+ });++ expect(await host.stop()).toBeNull();++ expect(await owed(host)).toBe(true);+});++it('stops owing a start Switch refused, rather than sending it forever', async () => {+ const host = await start({ owedStart: 'user', startRefused: true });+ try {+ await vi.waitFor(() => expect(startReports(host)).toHaveLength(1), { timeout: 5000 });+ await vi.waitFor(async () => expect(await owed(host)).toBe(false), { timeout: 3000 });+ } finally {+ expect(await host.stop()).toBeNull();+ }+});++it('drops a start record it cannot read without sending anything or failing', async () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const host = await start({ owedStartText: '{"startSource":"sometime"}' });+ try {+ await vi.waitFor(async () => expect(await owed(host)).toBe(false), { timeout: 5000 });+ expect(startReports(host)).toEqual([]);+ expect(warn).toHaveBeenCalledWith(+ expect.stringContaining('Could not read how this session started')+ );+ } finally {+ expect(await host.stop()).toBeNull();+ }+});++it('keeps the session running when the start record cannot even be removed', async () => {+ // Telemetry never takes a session down: the report is lost, the session is not.+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const host = await start({ rooms: true, owedStartBlocked: true });+ try {+ await vi.waitFor(+ () =>+ expect(warn).toHaveBeenCalledWith(+ expect.stringContaining('Could not report how this session started')+ ),+ { timeout: 5000 }+ );+ await host.parent.ask({ type: 'room', handoff: roomMessage(1, 'Still here?') });+ await vi.waitFor(+ () => expect(host.switchCore.calls.some((c) => c.path.endsWith('/activity'))).toBe(true),+ { timeout: 5000 }+ );+ expect(startReports(host)).toEqual([]);+ } finally {+ expect(await host.stop()).toBeNull();+ }+}, 20000);diff --git a/console/packages/agent-providers/src/host/shared-host.ts b/console/packages/agent-providers/src/host/shared-host.tsindex bfd229a84..6cfdfe676 100644--- a/console/packages/agent-providers/src/host/shared-host.ts+++ b/console/packages/agent-providers/src/host/shared-host.ts@@ -19,6 +19,7 @@ import {import { connectParent, type ParentChannel, type ParentPort } from './session-channel';import { HostedSession } from './session-host';import { startSessionMcp } from './session-mcp';+import { owedSessionStart, settleSessionStart, type OwedSessionStart } from './session-start';import { prepareSharedConfig, type SharedHostConfig } from './shared-config';import { SharedState } from './shared-state';@@ -31,8 +32,9 @@ import { SharedState } from './shared-state';* agent's sidecar for a remote one) and takes everything over that IPC* channel: room messages the agent's controller routed to it, commands from* Console, room controls and approval wakes. What it reports goes to the- * `/agent-sessions` routes: a row per turn step, the requests a person can- * answer, and the acknowledgement of answers it has applied.+ * `/agent-sessions` routes: that a new session started and how, a row per+ * turn step, the requests a person can answer, and the acknowledgement of+ * answers it has applied.** A host with a parent parks itself after `parkAfterMs` with nothing to do:* it records `parked` and exits, and its parent starts it again when the@@ -598,10 +600,53 @@ export async function runSharedHost();if (applied) await sendFollowup(owed);}+ /**+ * Tells the server, once, that this session is new and how it started —+ * what its launcher recorded when it created the state root. Owed until+ * the server answers, so a host stopped before then reports it next time;+ * the server counts a repeat once.+ *+ * Its own failures stay its own. A server that predates the route answers+ * a bare 404, which says nothing about the activity routes, so it is not+ * taken as the `unsupported` that switches all reporting off.+ */+ const reportStart = async (): Promise<void> => {+ try {+ let owed: OwedSessionStart | 'unreadable' | null;+ try {+ owed = await owedSessionStart(options.root);+ } catch (error) {+ console.warn(+ `Could not read how this session started, so it is not reported: ${String(error)}`+ );+ owed = 'unreadable';+ }+ if (owed === null) return;+ if (owed !== 'unreadable') {+ try {+ await agentSessions(`${sessionPath}/started`, 'POST', { start_source: owed });+ } catch (error) {+ if (!(error instanceof RequestError)) throw error;+ if (error.status === 404 && !error.code)+ console.warn(+ 'This Switch server does not accept session start reports, so how this session started is not reported.'+ );+ else console.warn(`Switch refused this session's start report: ${error.message}`);+ }+ }+ await settleSessionStart(options.root);+ } catch (error) {+ // Stopping is the one reason to let go: whatever is still owed is+ // reported the next time this session's host runs.+ if (executionSignal.aborted) throw error;+ console.warn(`Could not report how this session started: ${String(error)}`);+ }+ };// Reporting runs beside the session rather than in its way: while Switch// is unreachable the reports wait and retry, and the session keeps working.let reportingFailure: unknown = null;reporting = (async () => {+ await reportStart();let force = true;while (!executionSignal.aborted) {await report();diff --git a/console/packages/agent-providers/src/host/shared-watcher.test.ts b/console/packages/agent-providers/src/host/shared-watcher.test.tsindex c2dfe1ee6..c3e3054e0 100644--- a/console/packages/agent-providers/src/host/shared-watcher.test.ts+++ b/console/packages/agent-providers/src/host/shared-watcher.test.ts@@ -1054,6 +1054,8 @@ it('hands a session it has just created the event that created it', async () =>expect(started[0]!.parked).toMatchObject([{ sequence: 1, roomId: 'room', messageId: 'message-1' },]);+ // Started because the room addressed the agent, which its host reports.+ expect(vi.mocked(ensureSharedProcess).mock.calls[0]![0].startSource).toBe('room');expect(hosts.to(join(root, assigned!.session.sessionId))).toMatchObject([{type: 'room',diff --git a/console/packages/agent-providers/src/host/shared-watcher.ts b/console/packages/agent-providers/src/host/shared-watcher.tsindex 9c52379ed..69fd685b9 100644--- a/console/packages/agent-providers/src/host/shared-watcher.ts+++ b/console/packages/agent-providers/src/host/shared-watcher.ts@@ -614,6 +614,9 @@ export async function runSharedWatcher(watcher: false,restart: false,supervision,+ // Every session this watcher starts answers a room message. Recorded+ // only if this launch creates the session, so a relaunch is not a start.+ startSource: 'room',});};const superseded = await supersededSessions(template.session.agentId, supervision);diff --git a/console/packages/agent-providers/src/index.ts b/console/packages/agent-providers/src/index.tsindex a456e8106..67de28a7a 100644--- a/console/packages/agent-providers/src/index.ts+++ b/console/packages/agent-providers/src/index.ts@@ -57,6 +57,7 @@ export {sharedSessionRoot,} from './host/launch';export type { Supervision } from './host/launch';+export { hostStartSources, type HostStartSource } from './host/session-start';export { runSharedWatcher } from './host/shared-watcher';export { clearTakenOver, readTakenOver, type TakenOver } from './host/taken-over';export {diff --git a/console/packages/agent-providers/src/testing/agent-sessions-server.ts b/console/packages/agent-providers/src/testing/agent-sessions-server.tsindex 19bd8c590..4db308bd1 100644--- a/console/packages/agent-providers/src/testing/agent-sessions-server.ts+++ b/console/packages/agent-providers/src/testing/agent-sessions-server.ts@@ -13,10 +13,19 @@ export type AgentSessionsCall = { method: string; path: string; body: unknown };* Setting `state.unavailable` answers every such call with 503, as an* unreachable Switch would, and `state.refusesUsage` refuses an activity row* carrying usage with 422, as a server that predates it does.+ * `state.startUnknown` answers a session start report with a bare 404, as a+ * server that predates that route does, and `state.startRefused` refuses one+ * with 422.*/export function stubSwitchFetch(server: Fetch, outcomes: unknown[] = []) {const calls: AgentSessionsCall[] = [];- const state = { outcomes, unavailable: false, refusesUsage: false };+ const state = {+ outcomes,+ unavailable: false,+ refusesUsage: false,+ startUnknown: false,+ startRefused: false,+ };vi.stubGlobal('fetch', async (url: string, options: RequestInit = {}) => {const path = new URL(url).pathname;if (!path.includes('/agent-sessions/')) return server(url, options);@@ -31,6 +40,12 @@ export function stubSwitchFetch(server: Fetch, outcomes: unknown[] = []) {const listed = state.outcomes;return Response.json(listed);}+ if (path.endsWith('/started')) {+ if (state.startUnknown) return Response.json({ detail: 'Not Found' }, { status: 404 });+ if (state.startRefused)+ return Response.json({ detail: [{ type: 'literal_error' }] }, { status: 422 });+ return Response.json({ reported: true });+ }if (path.endsWith('/activity')) {const body = calls.at(-1)!.body as Record<string, unknown>;if (state.refusesUsage && 'usage' in body)diff --git a/core/switch_core/bridges/agent/api/activity_routes.py b/core/switch_core/bridges/agent/api/activity_routes.pyindex 5407dba77..27b47589c 100644--- a/core/switch_core/bridges/agent/api/activity_routes.py+++ b/core/switch_core/bridges/agent/api/activity_routes.py@@ -1,4 +1,5 @@-"""What an agent's session host reports: turn steps and approval requests.+"""What an agent's session host reports: that a session started, its turn steps+and its approval requests.The host owns the session; these routes take only what a messaging platformshows and what the server must check when a person answers. The agent is the@@ -7,6 +8,7 @@ one the API key belongs to, so a host can only ever write for its own agent.from datetime import datetimefrom typing import Annotated, Any, Literal+from uuid import UUIDfrom fastapi import APIRouter, Dependsfrom pydantic import BaseModel, ConfigDict, Field@@ -14,7 +16,11 @@ from pydantic.alias_generators import to_camelfrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerfrom switch_core.bridges.agent.auth import get_agent_from_scope-from switch_core.bridges.agent.dependencies import get_session_factory+from switch_core.bridges.agent.dependencies import (+ get_session_factory,+ get_session_start_limiter,+ get_telemetry,+)from switch_core.db.models import Agent, ApprovalRequestfrom switch_core.session_activity.service import (MAX_DETAIL_CHARS,@@ -29,10 +35,18 @@ from switch_core.session_activity.service import (QuestionOption,SessionActivityService,)+from switch_core.telemetry import TelemetryService+from switch_core.telemetry.session_start import (+ SessionStartLimiter,+ StartSource,+ report_session_started,+)router = APIRouter(prefix="/agent-sessions")Factory = Annotated[async_sessionmaker[AsyncSession], Depends(get_session_factory)]AuthenticatedAgent = Annotated[Agent, Depends(get_agent_from_scope)]+Telemetry = Annotated[TelemetryService | None, Depends(get_telemetry)]+Limiter = Annotated[SessionStartLimiter, Depends(get_session_start_limiter)]_Id = Annotated[str, Field(min_length=1, max_length=200)]@@ -45,6 +59,17 @@ _MAX_MODELS_PER_TURN = 50_MAX_TOKENS = 2**53 - 1+class SessionStart(BaseModel):+ model_config = ConfigDict(extra="forbid")+ start_source: StartSource+++class SessionStartReceipt(BaseModel):+ # False when nothing was sent: telemetry is off, or this session already+ # reported its start. A host acts on neither; it is here for the logs.+ reported: bool++class TokenUsageIn(BaseModel):model_config = ConfigDict(extra="forbid")model: str = Field(max_length=_MAX_MODEL_CHARS)@@ -154,6 +179,26 @@ class ApprovalView(_Response):)[email protected]("/{session_id}/started")+async def report_started(+ session_id: UUID,+ body: SessionStart,+ agent: AuthenticatedAgent,+ factory: Factory,+ telemetry: Telemetry,+ limiter: Limiter,+) -> SessionStartReceipt:+ """A session host saying, once, that a new session began and how.++ The id must be a UUID, which every launcher mints, so a caller cannot fill+ the claims with arbitrary strings.+ """+ reported = await report_session_started(+ telemetry, factory, limiter, agent, str(session_id), body.start_source+ )+ return SessionStartReceipt(reported=reported)++@router.post("/{session_id}/activity", response_model_by_alias=True)async def report_activity(session_id: _Id, body: ActivityReport, agent: AuthenticatedAgent, factory: Factorydiff --git a/core/switch_core/bridges/agent/api/handlers.py b/core/switch_core/bridges/agent/api/handlers.pyindex 8c16ba2ec..a1bebd5e4 100644--- a/core/switch_core/bridges/agent/api/handlers.py+++ b/core/switch_core/bridges/agent/api/handlers.py@@ -898,11 +898,11 @@ async def _open_event_stream(# created instead counted every rejected attempt as a session that began# and ended at once, which a retrying client repeats indefinitely.#- # `stream_generation == 0` keeps a supervisor reattaching to a connection- # it already had from reading as a new session: `open()` hands back the- # existing Connection and bumps the generation rather than making another.- if conn.stream_generation == 0:- await protocol.sessions.started(agent, conn)+ # Every stream, a reattach included. The reporter keys sessions on the+ # agent, so a stream on a connection the agent already holds continues its+ # session rather than starting another, and an open that failed after+ # registering its connection, retried on the same id, is still counted.+ await protocol.sessions.started(agent, conn)return StreamingResponse(event_stream(diff --git a/core/switch_core/bridges/agent/dependencies.py b/core/switch_core/bridges/agent/dependencies.pyindex 54cc19e32..230fc3ee8 100644--- a/core/switch_core/bridges/agent/dependencies.py+++ b/core/switch_core/bridges/agent/dependencies.py@@ -24,6 +24,10 @@ from switch_core.db.stores.room_store import RoomStorefrom switch_core.db.stores.task_store import TaskStorefrom switch_core.room_service import RoomServicefrom switch_core.telemetry import TelemetryService+from switch_core.telemetry.session_start import (+ SessionStartLimiter,+ default_session_start_limiter,+)if TYPE_CHECKING:from switch_core.session_activity.outcomes import ApprovalOutcomes@@ -69,6 +73,7 @@ def init_dependencies(_state["session_factory"] = session_factory_state["config"] = config_state["telemetry"] = telemetry+ _state["session_start_limiter"] = default_session_start_limiter()_state["protocol"] = ProtocolService(agent_store=agent_store,@@ -145,5 +150,13 @@ def get_protocol() -> ProtocolService:return _state["protocol"] # type: ignore[no-any-return]+def get_telemetry() -> TelemetryService | None:+ return cast(TelemetryService | None, _state.get("telemetry"))+++def get_session_start_limiter() -> SessionStartLimiter:+ return cast(SessionStartLimiter, _state["session_start_limiter"])++def get_session_factory() -> async_sessionmaker[AsyncSession]:return cast(async_sessionmaker[AsyncSession], _state["session_factory"])diff --git a/core/switch_core/bridges/collaboration/install_service.py b/core/switch_core/bridges/collaboration/install_service.pyindex 062d3f678..2a3beafa5 100644--- a/core/switch_core/bridges/collaboration/install_service.py+++ b/core/switch_core/bridges/collaboration/install_service.py@@ -255,6 +255,9 @@ class MessagingInstallService:# app create channels in a customer's workspace is a decision# someone should make rather than inherit.channel_creation_enabled=False,+ # A person installed the app: this is them connecting their+ # platform, which is exactly what onboarding measures.+ preconfigured=False,)async with tenant_session(diff --git a/core/switch_core/bridges/collaboration/lifecycle_service.py b/core/switch_core/bridges/collaboration/lifecycle_service.pyindex 2414720b3..9243dc1fc 100644--- a/core/switch_core/bridges/collaboration/lifecycle_service.py+++ b/core/switch_core/bridges/collaboration/lifecycle_service.py@@ -288,6 +288,7 @@ class CollaborationBridgeLifecycleService:_telemetry: TelemetryService | None = None_connect_failures: dict[str, int] = {}_bridge_facts: dict[str, tuple[str, object]] = {}+ _preconfigured: set[str] = set()_connected: set[str] = set()def __init__(@@ -342,6 +343,11 @@ class CollaborationBridgeLifecycleService:# Read off the row at start, so reporting never depends on what the# BridgeCore exposes.self._bridge_facts: dict[str, tuple[str, object]] = {}+ # Bridges the deployment's setup step registered rather than a person,+ # read off the row at start like `_bridge_facts`. Onboarding telemetry+ # leaves these out: a bundled connector coming up is a deployment+ # booting, not someone connecting their platform.+ self._preconfigured: set[str] = set()# Reached the platform, as opposed to merely started.self._connected: set[str] = set()# bridge_id -> the host resource it holds exclusively while running@@ -631,6 +637,7 @@ class CollaborationBridgeLifecycleService:display_name: str,connection_config: dict[str, object],channel_creation_enabled: bool,+ preconfigured: bool,) -> CollaborationBridge:async with self._register_lock:return await self._register_locked(@@ -638,6 +645,7 @@ class CollaborationBridgeLifecycleService:display_name=display_name,connection_config=connection_config,channel_creation_enabled=channel_creation_enabled,+ preconfigured=preconfigured,)async def _register_locked(@@ -647,6 +655,7 @@ class CollaborationBridgeLifecycleService:display_name: str,connection_config: dict[str, object],channel_creation_enabled: bool,+ preconfigured: bool,) -> CollaborationBridge:adapter_cls = self._adapter_registry.get(bridge_type)config_cls = self._config_registry.get(bridge_type)@@ -689,6 +698,7 @@ class CollaborationBridgeLifecycleService:client_id=bridge_client_record.id,status="active",channel_creation_enabled=channel_creation_enabled,+ preconfigured=preconfigured,)async with self._session_factory() as session:await self._bridge_store.create(session, bridge)@@ -700,7 +710,10 @@ class CollaborationBridgeLifecycleService:emit_safely(self._telemetry,"connector_configured",- {"bridge_platform": normalise_platform(bridge_type)},+ {+ "bridge_platform": normalise_platform(bridge_type),+ "is_preconfigured": preconfigured,+ },)await self.start(bridge.id)@@ -856,6 +869,10 @@ class CollaborationBridgeLifecycleService:# Stashed rather than passed: `_run_bridge`'s signature is what# the tenant-binding tests patch.self._bridge_facts[bridge_id] = (bridge.type, bridge.created_at)+ if bridge.preconfigured:+ self._preconfigured.add(bridge_id)+ else:+ self._preconfigured.discard(bridge_id)task = asyncio.create_task(self._run_bridge(bridge_id, tenant_id, bridge_core, bridge_client))@@ -1051,7 +1068,11 @@ class CollaborationBridgeLifecycleService:`bridge_connected` fires every time, so a flapping bridge shows up.`connector_added` fires only on the first ever connect.+ `first_connector_added` is the first connector a *person* added: a+ preconfigured one never claims it, or the bundled Mattermost would+ take it seconds after install on every deployment that ships one."""+ preconfigured = bridge_id in self._preconfiguredemit_safely(self._telemetry,"bridge_connected",@@ -1076,9 +1097,11 @@ class CollaborationBridgeLifecycleService:):# This bridge has reported, but the deployment-wide milestone may# not have. `emit_milestone` is itself once-ever.- await self._telemetry.emit_milestone(- "first_connector_added", bridge_platform=normalise_platform(platform)- )+ if not preconfigured:+ await self._telemetry.emit_milestone(+ "first_connector_added",+ bridge_platform=normalise_platform(platform),+ )returnelapsed_since_install = seconds_since_install(self._telemetry.installed_at)@@ -1093,19 +1116,39 @@ class CollaborationBridgeLifecycleService:elapsed_since_install if elapsed_since_install is not None else -1.0),"seconds_since_configured": seconds_since(configured_at),- "is_first_connector": not self._any_connector_before(bridge_id),+ "is_preconfigured": preconfigured,+ "is_first_connector": (+ not preconfigured and not self._any_connector_before(bridge_id)+ ),"failed_attempts_before_success": self._connect_failures.pop(bridge_id, 0),},)- await self._telemetry.emit_milestone(- "first_connector_added", bridge_platform=normalise_platform(platform)- )+ if not preconfigured:+ await self._telemetry.emit_milestone(+ "first_connector_added", bridge_platform=normalise_platform(platform)+ )++ def note_preconfigured(self, bridge_id: str, preconfigured: bool) -> None:+ """Follow a change to the row without a restart. Only a bridge this+ process has started is tracked; any other reads the row when it+ starts."""+ if bridge_id not in self._bridge_facts:+ return+ if preconfigured:+ self._preconfigured.add(bridge_id)+ else:+ self._preconfigured.discard(bridge_id)def _any_connector_before(self, bridge_id: str) -> bool:- """Whether another bridge was already connected when this one came up."""- return any(other != bridge_id for other in self._bridges)+ """Whether another bridge a person added was already running when this+ one came up. A preconfigured one does not count: it is there before+ anybody does anything."""+ return any(+ other != bridge_id and other not in self._preconfigured+ for other in self._bridges+ )async def stop(self, bridge_id: str, *, reason: str = "shutdown") -> None:# Before the adapter goes, so a press in flight is answered as gone@@ -1244,6 +1287,7 @@ class CollaborationBridgeLifecycleService:# Bridge ids are fresh UUIDs, so a deployment that repeatedly connects# and removes connectors grows these without bound otherwise.self._bridge_facts.pop(bridge_id, None)+ self._preconfigured.discard(bridge_id)self._connect_failures.pop(bridge_id, None)self._connect_started.pop(bridge_id, None)diff --git a/core/switch_core/clients/admin_messages.py b/core/switch_core/clients/admin_messages.pyindex d355aca5b..32d1c2ea0 100644--- a/core/switch_core/clients/admin_messages.py+++ b/core/switch_core/clients/admin_messages.py@@ -4,6 +4,16 @@ from collections.abc import Mappingfrom enum import StrEnumfrom typing import NamedTuple+# Content flag stamped on the no-session / busy-elsewhere auto-reply (see+# AgentClient.on_message). Its first job is to mark a message as itself an+# auto-reply so that another offline agent addressed by it does NOT emit a+# second auto-reply — two session-less agents tagging each other would+# otherwise ping-pong identical "no session" replies forever. It also lets the+# usage snapshot tell a notice Switch posted under an agent's name from+# something the agent said. Riding as a field on the plain m.room.message+# keeps the reply rendering normally for humans.+AUTO_REPLY_FLAG = "com.switch.auto_reply"+# Marker stamped on the content of an admin/system `m.room.message`. Two jobs,# mirroring AUTO_REPLY_FLAG:# 1. It tells the collaboration bridge to render the message through thediff --git a/core/switch_core/clients/agent_client.py b/core/switch_core/clients/agent_client.pyindex c311dc9ca..65412b25b 100644--- a/core/switch_core/clients/agent_client.py+++ b/core/switch_core/clients/agent_client.py@@ -34,6 +34,7 @@ from switch_core.bridges.agent.protocol.types import (TaskUpdatePayload,)from switch_core.clients.admin_messages import (+ AUTO_REPLY_FLAG,PLATFORM_MARKER,platform_on_behalf_of,platform_replies_in_channel,@@ -91,14 +92,6 @@ if TYPE_CHECKING:logger = logging.getLogger(__name__)-# Content flag stamped on the no-session / busy-elsewhere auto-reply (see-# on_message). Its only job is to mark a message as itself an auto-reply so that-# another offline agent addressed by it does NOT emit a second auto-reply — two-# session-less agents tagging each other would otherwise ping-pong identical-# "no session" replies forever. Riding as a field on the plain-# m.room.message keeps the reply rendering normally for humans.-AUTO_REPLY_FLAG = "com.switch.auto_reply"-# How long to hold an incomplete multi-attachment group before delivering the# parts that did arrive, flagged as incomplete. Groups normally complete in# milliseconds (one sender, back-to-back events); this is a safety net so adiff --git a/core/switch_core/db/models.py b/core/switch_core/db/models.pyindex 0a175260a..e3ecf2580 100644--- a/core/switch_core/db/models.py+++ b/core/switch_core/db/models.py@@ -1191,6 +1191,13 @@ class CollaborationBridge(TenantScoped, Base):is_default: Mapped[bool] = mapped_column(Boolean, server_default="false", nullable=False)+ # Registered by the deployment's own setup step — the bundled Mattermost —+ # rather than by a person. Telemetry reads it so that "time to first+ # connector" measures a person connecting their platform, not a+ # deployment booting.+ preconfigured: Mapped[bool] = mapped_column(+ Boolean, server_default="false", nullable=False+ )created_at: Mapped[str] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)diff --git a/core/switch_core/db/stores/collaboration_bridge_store.py b/core/switch_core/db/stores/collaboration_bridge_store.pyindex c62e355a4..134bdc67d 100644--- a/core/switch_core/db/stores/collaboration_bridge_store.py+++ b/core/switch_core/db/stores/collaboration_bridge_store.py@@ -105,6 +105,16 @@ class CollaborationBridgeStore:await session.flush()return bridge+ async def set_preconfigured(+ self, session: AsyncSession, bridge_id: str, preconfigured: bool+ ) -> CollaborationBridge:+ bridge = await session.get(CollaborationBridge, bridge_id)+ if bridge is None:+ raise ValueError(f"Bridge not found: {bridge_id}")+ bridge.preconfigured = preconfigured+ await session.flush()+ return bridge+async def merge_connection_config(self, session: AsyncSession, bridge_id: str, changes: dict[str, object]) -> CollaborationBridge:diff --git a/core/switch_core/gateway/collaborations.py b/core/switch_core/gateway/collaborations.pyindex 3490b6216..b07dae68e 100644--- a/core/switch_core/gateway/collaborations.py+++ b/core/switch_core/gateway/collaborations.py@@ -126,6 +126,7 @@ async def _detail(status=bridge.status,agent_greetings_enabled=bridge.agent_greetings_enabled,is_default=bridge.is_default if is_default is None else is_default,+ preconfigured=bridge.preconfigured,room_count=room_count,created_at=str(bridge.created_at),home_url=await _home_url(bridge.id, collab_lifecycle),@@ -178,6 +179,7 @@ async def create_bridge(display_name=req.display_name,connection_config=dict(req.connection_config),channel_creation_enabled=req.channel_creation_enabled,+ preconfigured=req.preconfigured,)except BridgeCredentialError as exc:# The platform's own words, verbatim — it knows what is wrong with the@@ -286,6 +288,10 @@ async def update_bridge(bridge = await bridge_store.set_channel_creation_enabled(session, bridge_id, payload.channel_creation_enabled)+ if payload.preconfigured is not None:+ bridge = await bridge_store.set_preconfigured(+ session, bridge_id, payload.preconfigured+ )if payload.connection_config is not None:merged = {**(bridge.connection_config or {}), **payload.connection_config}try:@@ -303,6 +309,8 @@ async def update_bridge(# next deploy.if payload.connection_config is not None:await collab_lifecycle.restart(bridge_id)+ if payload.preconfigured is not None:+ collab_lifecycle.note_preconfigured(bridge_id, payload.preconfigured)rooms = await room_store.get_by_bridge(session, bridge_id)return await _detail(bridge, room_count=len(rooms), collab_lifecycle=collab_lifecyclediff --git a/core/switch_core/gateway/schemas.py b/core/switch_core/gateway/schemas.pyindex d8178781c..e8199dbcf 100644--- a/core/switch_core/gateway/schemas.py+++ b/core/switch_core/gateway/schemas.py@@ -462,6 +462,9 @@ class BridgeDetail(BaseModel):status: stragent_greetings_enabled: boolis_default: bool+ # Registered by the deployment's own setup step rather than by a person.+ # See `BridgeCreateRequest.preconfigured`.+ preconfigured: boolroom_count: intcreated_at: str# Link that opens this bridge's workspace in its messaging app, built by@@ -497,6 +500,9 @@ class BridgeUpdateRequest(BaseModel):# a field it did not mention.agent_greetings_enabled: bool | None = Nonechannel_creation_enabled: bool | None = None+ # See `BridgeCreateRequest.preconfigured`. Settable afterwards so the setup+ # step can mark a connection it registered before the field existed.+ preconfigured: bool | None = None# Merged over the stored config, not substituted for it, so changing one# setting does not mean re-sending the platform's secrets. The merged# result is validated against the bridge type's schema before it is kept,@@ -529,6 +535,11 @@ class BridgeCreateRequest(BaseModel):# to keep existing callers behaving as they did; registration rejects it# for a platform that cannot, rather than storing a claim it cannot honour.channel_creation_enabled: bool = True+ # Registered by the deployment's own setup step rather than by a person.+ # Set by the headless standalone bootstrap for the Mattermost it bundles,+ # so onboarding telemetry measures a person connecting their platform+ # rather than the deployment booting. Everyone else leaves it off.+ preconfigured: bool = Falseclass IdentityClaimant(BaseModel):diff --git a/core/switch_core/migrations/versions/f4c8a2d61e93_collaboration_bridges_preconfigured.py b/core/switch_core/migrations/versions/f4c8a2d61e93_collaboration_bridges_preconfigured.pynew file mode 100644index 000000000..034b83e87--- /dev/null+++ b/core/switch_core/migrations/versions/f4c8a2d61e93_collaboration_bridges_preconfigured.py@@ -0,0 +1,35 @@+"""add preconfigured to collaboration_bridges++Revision ID: f4c8a2d61e93+Revises: d7a2e4c91b35++Marks a connection the deployment's setup step registered itself, as opposed+to one a person added. Existing rows are left false rather than guessed at: the+setup step marks the connection it owns the next time it runs.+"""++from collections.abc import Sequence++import sqlalchemy as sa+from alembic import op++revision: str = "f4c8a2d61e93"+down_revision: str | Sequence[str] | None = "d7a2e4c91b35"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None+++def upgrade() -> None:+ op.add_column(+ "collaboration_bridges",+ sa.Column(+ "preconfigured",+ sa.Boolean(),+ server_default="false",+ nullable=False,+ ),+ )+++def downgrade() -> None:+ op.drop_column("collaboration_bridges", "preconfigured")diff --git a/core/switch_core/telemetry/catalogue.py b/core/switch_core/telemetry/catalogue.pyindex a52c68f7d..07d2126f7 100644--- a/core/switch_core/telemetry/catalogue.py+++ b/core/switch_core/telemetry/catalogue.py@@ -172,7 +172,7 @@ _SNAPSHOT_COUNTS = ("agent_other_count",# Connections, not distinct agents: an agent may hold several. No# "sessions started today" — nothing durable records one, so it could only- # be an in-process tally a restart resets. `agent_session_started` covers it.+ # be an in-process tally a restart resets. `session_started` covers it."session_live_count","connector_slack_count","connector_mattermost_count",@@ -222,6 +222,8 @@ CATALOGUE: Mapping[str, Mapping[str, PropertyType]] = {# At most once per deployment, and only for one installed after this# shipped. Together they are the activation funnel."deployment_installed": dict(_SINCE_INSTALL),+ # The first connector a person added. One the setup step registered itself+ # never claims it, or the bundled Mattermost would, seconds after install."first_connector_added": {**_SINCE_INSTALL, "bridge_platform": BRIDGE_PLATFORM},"first_room_created": {**_SINCE_INSTALL,@@ -299,9 +301,20 @@ CATALOGUE: Mapping[str, Mapping[str, PropertyType]] = {"registration_path": one_of("bootstrap", "personal_key", "gateway", "other"),"has_parent": BOOLEAN,},- # No "start source": the server sees an authenticated connection whether a- # person launched the session or Console spawned it.+ # An agent coming online: its first live connection. No "start source": the+ # server sees an authenticated connection whether a person launched the+ # session or Console spawned it. `session_started` is the one that says."agent_session_started": {"known_agent_type": KNOWN_AGENT_TYPE},+ # A coding-agent session starting, as its host reports it once, when the+ # session is new. `start_source` is what the launcher stamped on it: `user`+ # a person starting one in Console, `room` the agent being addressed in a+ # room, `automation` Console's local automation API, and `unknown` a+ # launcher that said nothing — reported rather than dropped, so a launch+ # path nobody stamped shows up as a gap instead of as no sessions.+ "session_started": {+ "start_source": one_of("user", "room", "automation", "unknown"),+ "known_agent_type": KNOWN_AGENT_TYPE,+ },# No runtime: the connection registry is the only thing that knows a# session ended and it holds none. Starts carry it."agent_session_ended": {@@ -314,6 +327,11 @@ CATALOGUE: Mapping[str, Mapping[str, PropertyType]] = {"bridge_platform": BRIDGE_PLATFORM,"seconds_since_install": NUMBER,"seconds_since_configured": NUMBER,+ # Registered by the deployment's setup step (the bundled Mattermost)+ # rather than by a person. Filter these out to measure onboarding.+ "is_preconfigured": BOOLEAN,+ # The first connector a person added: never true for a preconfigured+ # one, and a preconfigured one already running does not make it false."is_first_connector": BOOLEAN,"failed_attempts_before_success": NUMBER,},@@ -406,7 +424,10 @@ CATALOGUE: Mapping[str, Mapping[str, PropertyType]] = {"server_connector_removed": {"connector_kind": one_of("opencode", "other")},# Configured, not connected. Many of these and few `bridge_connected` is a# deployment whose setup is failing.- "connector_configured": {"bridge_platform": BRIDGE_PLATFORM},+ "connector_configured": {+ "bridge_platform": BRIDGE_PLATFORM,+ "is_preconfigured": BOOLEAN,+ },"invitation_sent": {},"invitation_accepted": {"age_hours": NUMBER},"bridge_disconnected": {diff --git a/core/switch_core/telemetry/deployment.py b/core/switch_core/telemetry/deployment.pyindex 3cd39c97f..d4b7c5cf2 100644--- a/core/switch_core/telemetry/deployment.py+++ b/core/switch_core/telemetry/deployment.py@@ -16,7 +16,7 @@ import loggingfrom datetime import UTC, datetimefrom typing import Literal-from sqlalchemy import select+from sqlalchemy import delete, selectfrom sqlalchemy.dialects.postgresql import insert as pg_insertfrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker@@ -69,6 +69,28 @@ def seconds_since_install(installed_at: datetime | None) -> float | None:return max((datetime.now(UTC) - installed_at).total_seconds(), 0.0)+async def prune_claims(+ session_factory: async_sessionmaker[AsyncSession],+ *,+ prefix: str,+ claimed_before: datetime,+) -> int:+ """Delete claims named `prefix...` taken before `claimed_before`.++ Only for claims kept to absorb a repeat, never for a once-ever milestone:+ pruning one of those reports it again. Returns how many went.+ """+ async with session_factory() as session:+ result = await session.execute(+ delete(TelemetryMilestone).where(+ TelemetryMilestone.name.startswith(prefix, autoescape=True),+ TelemetryMilestone.emitted_at < claimed_before,+ )+ )+ await session.commit()+ return int(result.rowcount or 0) # type: ignore[attr-defined]++async def milestone_claimed(session_factory: async_sessionmaker[AsyncSession], name: str) -> Literal["true", "false", "unknown"]:diff --git a/core/switch_core/telemetry/reporter.py b/core/switch_core/telemetry/reporter.pyindex 2dc09e9ca..701b40b36 100644--- a/core/switch_core/telemetry/reporter.py+++ b/core/switch_core/telemetry/reporter.py@@ -22,6 +22,7 @@ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerfrom switch_core.db.models import TelemetrySnapshotWatermarkfrom switch_core.telemetry.deployment import claim_milestonefrom switch_core.telemetry.service import TelemetryService+from switch_core.telemetry.session_start import prune_session_start_claimsfrom switch_core.telemetry.snapshot import (as_utc,collect_usage,@@ -84,8 +85,22 @@ class SnapshotReporter:return Falseawait self.run_once(now=now, since=last_sent)await self._write_watermark(now)+ await self._prune(now)return True+ async def _prune(self, now: datetime) -> None:+ """Drop session start claims past their use, once a day with the+ snapshot. After the watermark, so a failure here can never make the+ snapshot go again; logged rather than raised, since the pass it rides+ on has already done its work."""+ try:+ pruned = await prune_session_start_claims(self._session_factory, now=now)+ except Exception:+ logger.exception("Pruning old session start claims failed")+ return+ if pruned:+ logger.info("Pruned %d session start claim(s) past their use", pruned)+async def run_once(self, *, now: datetime, since: datetime | None) -> None:"""Collect and report one snapshot, plus any room that just went live."""counts = await collect_usage(self._session_factory, now=now)diff --git a/core/switch_core/telemetry/session_start.py b/core/switch_core/telemetry/session_start.pynew file mode 100644index 000000000..b1df17942--- /dev/null+++ b/core/switch_core/telemetry/session_start.py@@ -0,0 +1,147 @@+"""A coding-agent session starting, as the host that runs it reports it.++The server cannot see this for itself. Sessions share their agent's one+connection, held by Console or a remote host's sidecar, so a session begins+without anything reaching the server, and who began it is known only to+whatever launched it. The host says so once, when the session is new, carrying+what the launcher stamped on it.+"""++from __future__ import annotations++import logging+import time+from collections import deque+from collections.abc import Callable+from datetime import datetime, timedelta+from typing import Literal++from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.db.models import Agent+from switch_core.telemetry.deployment import claim_milestone, prune_claims+from switch_core.telemetry.service import TelemetryService, emit_safely+from switch_core.telemetry.snapshot import normalise_known_agent_type++logger = logging.getLogger(__name__)++StartSource = Literal["user", "room", "automation", "unknown"]++# The claims share `telemetry_milestones` with the once-ever milestones and the+# per-connector claims, which are never pruned; the prefix is what tells them+# apart.+CLAIM_PREFIX = "session_started:"++# How long a claim is kept. It exists only so a retried report counts once, and+# a host retries within seconds while Switch answers, or the next time a+# session stopped mid-report runs. A report retried later than this, whose+# first attempt did reach the server, counts twice.+CLAIM_TTL = timedelta(days=7)++# Well above an agent starting a session for every room message it is+# addressed in, and low enough that one agent cannot fill the table or the+# dashboard with made-up sessions.+MAX_STARTS_PER_AGENT = 120+START_WINDOW_SECONDS = 3600.0+++class SessionStartLimiter:+ """How many start reports each agent may make in a sliding window.++ In memory, which is enough for what it guards: a restart resets it, and+ the most that buys an abusive agent is one more window's worth.+ """++ def __init__(+ self,+ *,+ max_per_window: int,+ window_seconds: float,+ clock: Callable[[], float],+ ) -> None:+ self._max = max_per_window+ self._window = window_seconds+ self._clock = clock+ self._seen: dict[str, deque[float]] = {}+ # Agents already warned about in their current burst, so a flood logs+ # once rather than once per report.+ self._warned: set[str] = set()++ def admit(self, agent_id: str) -> bool:+ now = self._clock()+ seen = self._seen.setdefault(agent_id, deque())+ while seen and now - seen[0] >= self._window:+ seen.popleft()+ if len(seen) >= self._max:+ if agent_id not in self._warned:+ self._warned.add(agent_id)+ logger.warning(+ "Agent %s reported more than %d session starts in %.0f "+ "seconds; further reports are not counted until the rate "+ "drops.",+ agent_id,+ self._max,+ self._window,+ )+ return False+ self._warned.discard(agent_id)+ seen.append(now)+ return True+++def default_session_start_limiter() -> SessionStartLimiter:+ return SessionStartLimiter(+ max_per_window=MAX_STARTS_PER_AGENT,+ window_seconds=START_WINDOW_SECONDS,+ clock=time.monotonic,+ )+++async def report_session_started(+ telemetry: TelemetryService | None,+ session_factory: async_sessionmaker[AsyncSession],+ limiter: SessionStartLimiter,+ agent: Agent,+ session_id: str,+ start_source: StartSource,+) -> bool:+ """Emit `session_started` for this session unless it already has.++ The claim is what makes a retried or repeated report count once, across+ restarts too: the host retries until the server answers, and an answer+ lost on the way back is a second report of the same start. Keyed by agent+ as well as session, so one agent's host cannot spend another's.++ Nothing is claimed while telemetry is off, for the reason+ `TelemetryService.emit_milestone` gives. Returns whether it was sent.+ """+ if telemetry is None or not telemetry.enabled:+ return False+ if not limiter.admit(agent.id):+ return False+ if not await claim_milestone(+ session_factory, f"{CLAIM_PREFIX}{agent.id}:{session_id}"+ ):+ return False+ emit_safely(+ telemetry,+ "session_started",+ {+ "start_source": start_source,+ "known_agent_type": normalise_known_agent_type(agent.metadata_),+ },+ )+ return True+++async def prune_session_start_claims(+ session_factory: async_sessionmaker[AsyncSession], *, now: datetime+) -> int:+ """Delete session start claims older than `CLAIM_TTL`. Returns how many.++ Only these: every other row in the table is a once-ever claim, and pruning+ one would report its milestone again.+ """+ return await prune_claims(+ session_factory, prefix=CLAIM_PREFIX, claimed_before=now - CLAIM_TTL+ )diff --git a/core/switch_core/telemetry/snapshot.py b/core/switch_core/telemetry/snapshot.pyindex 446fc5aed..158f61919 100644--- a/core/switch_core/telemetry/snapshot.py+++ b/core/switch_core/telemetry/snapshot.py@@ -36,6 +36,7 @@ from sqlalchemy import (from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerfrom sqlalchemy.orm import aliased+from switch_core.clients.admin_messages import AUTO_REPLY_FLAGfrom switch_core.db.models import (Agent,ApiKey,@@ -68,6 +69,11 @@ AGENT_CLIENT_TYPE = "agent"# omitting the property — the catalogue requires every key every time.PLATFORMS = ("slack", "mattermost", "discord", "teams", "telegram")+# What a participant said, as opposed to everything else the transport stores in+# the same table: arrivals, tool and LLM call reports, task transitions. A+# command typed on a platform is something a person said.+SPOKEN_EVENT_TYPES = ("m.room.message", "com.switch.command")+_DAY = timedelta(days=1)# How far back the turn pairing looks for a message's predecessor. See# `_collect_turns`.@@ -268,13 +274,29 @@ def _human_activity_conditions(tenant_id: str) -> tuple[Any, ...]:)+def _spoken() -> tuple[Any, ...]:+ """Something a participant said, not a row the transport stored beside it.++ Every durable event is a row in `messages`, so without this an agent+ joining a room or reporting a tool call reads as an agent message, and a+ person being added to a room reads as that person being active. The+ notice Switch posts under an agent's name when the agent cannot take a+ request is excluded too: the agent did not say it.+ """+ return (+ Message.event_type.in_(SPOKEN_EVENT_TYPES),+ ~Message.content.has_key(AUTO_REPLY_FLAG),+ )++def _human_message_conditions(tenant_id: str) -> tuple[Any, ...]:- """The message half of `_human_activity_conditions`: a person sent it, and+ """The message half of `_human_activity_conditions`: a person said it, andit is live traffic rather than a backfill."""return (Client.type == HUMAN_CLIENT_TYPE,Client.tenant_id == tenant_id,Message.seq > 0,+ *_spoken(),)@@ -426,6 +448,7 @@ async def collect_tenant_counts(Message.sent_at >= week_ago,Client.type == AGENT_CLIENT_TYPE,Client.tenant_id == tenant_id,+ *_spoken(),),)@@ -449,7 +472,10 @@ async def collect_tenant_counts(select(func.count()).select_from(Message).where(- Message.tenant_id == tenant_id, Message.sent_at >= day_ago, Message.seq > 0+ Message.tenant_id == tenant_id,+ Message.sent_at >= day_ago,+ Message.seq > 0,+ *_spoken(),),)by_sender = await session.execute(@@ -461,6 +487,7 @@ async def collect_tenant_counts(Message.sent_at >= day_ago,Message.seq > 0,Client.tenant_id == tenant_id,+ *_spoken(),).group_by(Client.type))@@ -577,6 +604,10 @@ async def _collect_turns(Message.tenant_id == tenant_id,Client.tenant_id == tenant_id,Message.seq > 0,+ # Before the window function, not after: an arrival or a report+ # between a question and its answer would otherwise be what the+ # answer is paired with.+ *_spoken(),# Bounded, or the window covers the tenant's whole history every# pass. The outer `sent_at` filter cannot be pushed in: the window# partitions by room, so narrowing the input would change whichdiff --git a/core/tests/deploy/test_setup_register_bridge.py b/core/tests/deploy/test_setup_register_bridge.pyindex a8d5d4ae7..b85375814 100644--- a/core/tests/deploy/test_setup_register_bridge.py+++ b/core/tests/deploy/test_setup_register_bridge.py@@ -233,3 +233,67 @@ def test_an_empty_list_still_registers_a_bridge(setup_script: Any) -> None:assert setup_script.register_bridge(client) == "bridge-new"assert writes == [("POST", "/gateway/collaborations")]+++def _recording(bridges: list[dict[str, Any]], sent: list[Any]) -> Any:+ """Like `_listing`, but keeps each write's body too."""++ def handler(request: httpx.Request) -> httpx.Response:+ if request.method == "GET":+ return httpx.Response(200, json=bridges)+ sent.append((request.method, request.url.path, json.loads(request.content)))+ return httpx.Response(200, json={"bridge_id": "bridge-new"})++ return handler+++def test_a_new_bridge_is_registered_as_preconfigured(setup_script: Any) -> None:+ """This step registers it, not a person, so telemetry must not count it as+ anyone connecting a platform."""+ sent: list[Any] = []++ with _client(_recording([], sent)) as client:+ setup_script.register_bridge(client)++ [(method, path, body)] = sent+ assert (method, path) == ("POST", "/gateway/collaborations")+ assert body["preconfigured"] is True+++def test_an_existing_bridge_not_yet_marked_is_marked_preconfigured(+ setup_script: Any,+) -> None:+ """A bridge this step registered before the flag existed."""+ sent: list[Any] = []+ bridges = [+ {+ "bridge_id": "bridge-1",+ "bridge_type": "mattermost",+ "is_default": True,+ "preconfigured": False,+ }+ ]++ with _client(_recording(bridges, sent)) as client:+ assert setup_script.register_bridge(client) == "bridge-1"++ assert sent == [+ ("PATCH", "/gateway/collaborations/bridge-1", {"preconfigured": True})+ ]+++def test_an_existing_bridge_already_marked_is_left_alone(setup_script: Any) -> None:+ writes: list[tuple[str, str]] = []+ bridges = [+ {+ "bridge_id": "bridge-1",+ "bridge_type": "mattermost",+ "is_default": True,+ "preconfigured": True,+ }+ ]++ with _client(_listing(bridges, writes)) as client:+ assert setup_script.register_bridge(client) == "bridge-1"++ assert writes == []diff --git a/core/tests/switch_core/bridges/agent/api/test_events_endpoint_dispatch.py b/core/tests/switch_core/bridges/agent/api/test_events_endpoint_dispatch.pyindex 3c7a3ef9b..8f05096cd 100644--- a/core/tests/switch_core/bridges/agent/api/test_events_endpoint_dispatch.py+++ b/core/tests/switch_core/bridges/agent/api/test_events_endpoint_dispatch.py@@ -7,6 +7,7 @@ coexist — but the dispatch itself is easy to break silently, hence these.from __future__ import annotations+import asynciofrom types import SimpleNamespacefrom typing import Any@@ -14,15 +15,19 @@ import pytestfrom fastapi import HTTPExceptionfrom starlette.responses import StreamingResponse+from switch_core.bridges.agent.api import session_reporterfrom switch_core.bridges.agent.api.handlers import _resolve_start_cursor, poll_eventsfrom switch_core.bridges.agent.api.session_reporter import SessionReporterfrom switch_core.bridges.agent.protocol.connections import (+ HEARTBEAT_LAPSED,PROTOCOL_ACCEPTS,PROTOCOL_VERSION,ClientDeclaration,ConnectionRegistry,)from switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.telemetry.service import TelemetryService+from switch_core.telemetry.sink import TelemetryRecordAGENT_ID = "agent-1"@@ -346,3 +351,122 @@ class TestDeclaringARoomAtOpenTakesOver:assert claimant is not Noneassert claimant.id == "supervisor"assert "room-1" not in incumbent.rooms+++class _RecordingSink:+ def __init__(self) -> None:+ self.sent: list[TelemetryRecord] = []++ async def send(self, record: TelemetryRecord) -> None:+ self.sent.append(record)++ async def aclose(self) -> None:+ return None+++class TestOpeningAStreamReportsASession:+ """Through the endpoint, not the reporter. Whether a connection is new is+ decided here, so a gate that never opens silences both session events+ while every test of the reporter alone stays green."""++ def _reporting(self) -> tuple[_Protocol, TelemetryService, _RecordingSink]:+ sink = _RecordingSink()+ service = TelemetryService(+ sink=sink, # type: ignore[arg-type]+ enabled=True,+ client_id="11111111-1111-1111-1111-111111111111",+ service_name="switch-core",+ version="1.0.0",+ environment=None,+ )+ protocol = _Protocol()+ protocol.sessions = SessionReporter(service, protocol.connections)+ protocol.connections.set_close_listener(protocol.sessions.on_close)+ return protocol, service, sink++ async def test_a_new_connection_reports_a_session_start(self) -> None:+ protocol, service, sink = self._reporting()++ await _call(protocol, accept="text/event-stream", connection_id="c1")+ await service.aclose()++ assert [r.name for r in sink.sent] == ["switch_core.agent_session_started"]++ async def test_a_reattach_to_the_same_connection_is_not_another_start(+ self,+ ) -> None:+ protocol, service, sink = self._reporting()++ await _call(protocol, accept="text/event-stream", connection_id="c1")+ await _call(protocol, accept="text/event-stream", connection_id="c1")+ await service.aclose()++ assert [r.name for r in sink.sent] == ["switch_core.agent_session_started"]++ async def test_a_refused_open_then_a_retry_is_one_start(self) -> None:+ """The room claim refuses the first attempt; nothing began, so only the+ retry that gets a stream reports."""+ protocol, service, sink = self._reporting()+ refusals = [PermissionError("not a member yet")]++ async def member(agent_id: str, room_id: str) -> None:+ if refusals:+ raise refusals.pop()++ protocol.require_room_member = member # type: ignore[method-assign]++ with pytest.raises(HTTPException):+ await _call(+ protocol, accept="text/event-stream", connection_id="c1", rooms="r1"+ )+ await _call(+ protocol, accept="text/event-stream", connection_id="c1", rooms="r1"+ )+ await service.aclose()++ assert [r.name for r in sink.sent] == ["switch_core.agent_session_started"]++ async def test_an_open_that_failed_after_registering_is_counted_on_retry(+ self,+ ) -> None:+ """An unexpected failure leaves the connection registered, so the retry+ on the same id reattaches to it. It is still the session's first+ stream."""+ protocol, service, sink = self._reporting()+ failures = [RuntimeError("database went away")]++ async def member(agent_id: str, room_id: str) -> None:+ if failures:+ raise failures.pop()++ protocol.require_room_member = member # type: ignore[method-assign]++ with pytest.raises(RuntimeError):+ await _call(+ protocol, accept="text/event-stream", connection_id="c1", rooms="r1"+ )+ assert protocol.connections.get("c1") is not None+ await _call(+ protocol, accept="text/event-stream", connection_id="c1", rooms="r1"+ )+ await service.aclose()++ assert [r.name for r in sink.sent] == ["switch_core.agent_session_started"]++ async def test_closing_the_only_connection_ends_the_session(+ self, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ """The end is reported only for a connection the start was reported+ on, so a start that never fires takes the end down with it."""+ monkeypatch.setattr(session_reporter, "_RECONNECT_GRACE_SECONDS", 0)+ protocol, service, sink = self._reporting()++ await _call(protocol, accept="text/event-stream", connection_id="c1")+ protocol.connections.close("c1", HEARTBEAT_LAPSED)+ await asyncio.sleep(0.01)+ await service.aclose()++ assert [r.name for r in sink.sent] == [+ "switch_core.agent_session_started",+ "switch_core.agent_session_ended",+ ]diff --git a/core/tests/switch_core/bridges/agent/api/test_reattach_refusal.py b/core/tests/switch_core/bridges/agent/api/test_reattach_refusal.pyindex b21d48f3a..f377e9daa 100644--- a/core/tests/switch_core/bridges/agent/api/test_reattach_refusal.py+++ b/core/tests/switch_core/bridges/agent/api/test_reattach_refusal.py@@ -18,6 +18,7 @@ import pytestfrom fastapi import HTTPExceptionfrom switch_core.bridges.agent.api.handlers import poll_events+from switch_core.bridges.agent.api.session_reporter import SessionReporterfrom switch_core.bridges.agent.protocol.connections import (PROTOCOL_VERSION,ClientDeclaration,@@ -35,6 +36,9 @@ class _Protocol:self.connections = ConnectionRegistry()# No approval outcomes: these tests are about opening the stream.self.approval_outcomes = None+ # Every stream a client is handed goes past the session reporter; one+ # with no telemetry service reports nothing.+ self.sessions = SessionReporter(None)self.declarations: list[ClientDeclaration] = []async def record_client_declaration(@@ -60,7 +64,7 @@ def _attach(protocol: _Protocol) -> Any:async def _reopen(protocol: _Protocol, expected_generation: int | None) -> Any:return await poll_events(AGENT_ID,- SimpleNamespace(id=AGENT_ID), # type: ignore[arg-type]+ SimpleNamespace(id=AGENT_ID, metadata_={}), # type: ignore[arg-type]protocol, # type: ignore[arg-type]accept="text/event-stream",connection_id=CONN_ID,diff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_type_registry.py b/core/tests/switch_core/bridges/collaboration/test_bridge_type_registry.pyindex 118517880..83010183f 100644--- a/core/tests/switch_core/bridges/collaboration/test_bridge_type_registry.py+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_type_registry.py@@ -162,6 +162,7 @@ async def test_registering_telegram_cannot_grant_channel_creation() -> None:display_name="Acme Telegram",connection_config={"bot_token": "t", "bot_username": "b"},channel_creation_enabled=True,+ preconfigured=False,)diff --git a/core/tests/switch_core/bridges/collaboration/test_install_service.py b/core/tests/switch_core/bridges/collaboration/test_install_service.pyindex a6879881d..ee1abf287 100644--- a/core/tests/switch_core/bridges/collaboration/test_install_service.py+++ b/core/tests/switch_core/bridges/collaboration/test_install_service.py@@ -291,6 +291,8 @@ class TestTheRoundTrip:registered = fixture.lifecycle.registered[0]assert registered["bridge_type"] == "slack"assert registered["display_name"] == "Acme"+ # A person clicked Add to Slack: onboarding telemetry must count it.+ assert registered["preconfigured"] is Falseassert install.bridge_id is not Noneasync def test_the_redirect_is_the_public_one_on_both_legs(diff --git a/core/tests/switch_core/bridges/collaboration/test_lifecycle_remove.py b/core/tests/switch_core/bridges/collaboration/test_lifecycle_remove.pyindex e605e055a..4a2724a9c 100644--- a/core/tests/switch_core/bridges/collaboration/test_lifecycle_remove.py+++ b/core/tests/switch_core/bridges/collaboration/test_lifecycle_remove.py@@ -364,3 +364,20 @@ async def test_a_starting_bridge_is_recorded_in_the_rooms_it_carries(async with session_factory() as session:assert await RoomStore().get_client_ids(session, room_id) == [client_id]assert await RoomStore().get_client_ids(session, elsewhere_id) == []+++async def test_removing_a_bridge_forgets_that_it_was_preconfigured(+ session_factory: async_sessionmaker[AsyncSession],+) -> None:+ """Bridge ids are never reused, so an entry left behind is one nothing+ will ever remove."""+ service = _service(session_factory, _ClientLifecycle())+ async with session_factory() as session:+ bridge_id, _ = await _make_bridge(session)+ await session.commit()+ service._preconfigured.add(bridge_id)++ await service.remove(bridge_id)++ assert bridge_id not in service._preconfigureddiff --git a/core/tests/switch_core/bridges/collaboration/test_teams_zero_config.py b/core/tests/switch_core/bridges/collaboration/test_teams_zero_config.pyindex b66315fa3..bb4ef501c 100644--- a/core/tests/switch_core/bridges/collaboration/test_teams_zero_config.py+++ b/core/tests/switch_core/bridges/collaboration/test_teams_zero_config.py@@ -344,6 +344,7 @@ async def test_register_prepares_then_verifies_before_touching_anything() -> Nondisplay_name="Recording",connection_config={"app_id": "a"},channel_creation_enabled=True,+ preconfigured=False,)assert _RecordingAdapter.events == ["prepare", "verify"]@@ -363,6 +364,7 @@ async def test_register_verifies_the_prepared_config_not_the_raw_request() -> Nodisplay_name="Recording",connection_config={"app_id": "a"},channel_creation_enabled=True,+ preconfigured=False,)assert _RecordingAdapter.seen_config["generated"] == "yes"@@ -480,6 +482,7 @@ async def test_second_teams_bridge_on_the_same_port_is_refused(display_name="Second Teams",connection_config=_raw_config(),channel_creation_enabled=True,+ preconfigured=False,)message = str(excinfo.value)@@ -509,6 +512,7 @@ async def test_a_second_bridge_on_its_own_port_is_allowed_through(display_name="Second Teams",connection_config=_raw_config(listen_port=3979),channel_creation_enabled=True,+ preconfigured=False,)@@ -531,6 +535,7 @@ async def test_a_non_teams_bridge_is_not_blocked_by_a_teams_one(display_name="Teams",connection_config=_raw_config(),channel_creation_enabled=True,+ preconfigured=False,)@@ -641,12 +646,14 @@ async def test_concurrent_registration_cannot_take_the_same_port_twice(display_name="Teams A",connection_config=_raw_config(),channel_creation_enabled=True,+ preconfigured=False,),service.register(bridge_type="teams",display_name="Teams B",connection_config=_raw_config(),channel_creation_enabled=True,+ preconfigured=False,),return_exceptions=True,)diff --git a/core/tests/switch_core/clients/test_addressing_enforcement.py b/core/tests/switch_core/clients/test_addressing_enforcement.pyindex 1bc1a6900..05d3d76a8 100644--- a/core/tests/switch_core/clients/test_addressing_enforcement.py+++ b/core/tests/switch_core/clients/test_addressing_enforcement.py@@ -3,8 +3,9 @@ from __future__ import annotationsfrom contextlib import asynccontextmanagerfrom types import SimpleNamespace+from switch_core.clients.admin_messages import AUTO_REPLY_FLAGfrom switch_core.clients.admin_messages import PLATFORM_MARKER as _PLATFORM_MARKER-from switch_core.clients.agent_client import AUTO_REPLY_FLAG, AgentClient+from switch_core.clients.agent_client import AgentClientfrom switch_core.delivery.addressing import (ADDRESSING_DENIED_MESSAGE as _ADDRESSING_DENIED_MESSAGE,)diff --git a/core/tests/switch_core/gateway/test_collaborations_preconfigured.py b/core/tests/switch_core/gateway/test_collaborations_preconfigured.pynew file mode 100644index 000000000..cebdbd068--- /dev/null+++ b/core/tests/switch_core/gateway/test_collaborations_preconfigured.py@@ -0,0 +1,176 @@+"""The gateway's side of `preconfigured`: the setup step sets it when it+registers the bundled Mattermost, marks a bridge it registered before the flag+existed, and reads it back to know whether it still has to."""++from __future__ import annotations++from typing import Any++from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.db.models import CollaborationBridge+from switch_core.gateway.collaborations import (+ create_bridge,+ list_bridges,+ update_bridge,+)+from switch_core.gateway.schemas import BridgeCreateRequest, BridgeUpdateRequest+from tests.switch_core.gateway.test_collaborations_authz import (+ _BRIDGE_STORE,+ _ROOM_STORE,+ _admin,+ _make_bridge,+ _NoRunningBridges,+)+++class _Lifecycle(_NoRunningBridges):+ """Records what the endpoints tell the running bridges."""++ def __init__(self, registered: CollaborationBridge | None = None) -> None:+ self.registered = registered+ self.register_kwargs: dict[str, Any] = {}+ self.noted: list[tuple[str, bool]] = []+ self.restarted: list[str] = []++ async def register(self, **kwargs: Any) -> CollaborationBridge:+ self.register_kwargs = kwargs+ assert self.registered is not None+ return self.registered++ def note_preconfigured(self, bridge_id: str, preconfigured: bool) -> None:+ self.noted.append((bridge_id, preconfigured))++ async def restart(self, bridge_id: str) -> None:+ self.restarted.append(bridge_id)+++def _request(**overrides: Any) -> BridgeCreateRequest:+ body: dict[str, Any] = {+ "bridge_type": "mattermost",+ "display_name": "Mattermost",+ "connection_config": {"url": "http://mattermost.invalid"},+ }+ body.update(overrides)+ return BridgeCreateRequest(**body)+++class TestRegistering:+ async def test_the_setup_steps_flag_reaches_the_lifecycle(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ bridge = await _BRIDGE_STORE.get(session, await _make_bridge(session))+ await session.commit()+ assert bridge is not None+ lifecycle = _Lifecycle(registered=bridge)++ async with session_factory() as session:+ await create_bridge(+ _request(preconfigured=True),+ session,+ _BRIDGE_STORE,+ lifecycle, # type: ignore[arg-type]+ _admin(),+ )++ assert lifecycle.register_kwargs["preconfigured"] is True++ async def test_a_person_registering_one_leaves_it_off(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Nobody but the setup step sends it, so a request without it is a+ person connecting their platform."""+ async with session_factory() as session:+ bridge = await _BRIDGE_STORE.get(session, await _make_bridge(session))+ await session.commit()+ lifecycle = _Lifecycle(registered=bridge)++ async with session_factory() as session:+ await create_bridge(+ _request(),+ session,+ _BRIDGE_STORE,+ lifecycle, # type: ignore[arg-type]+ _admin(),+ )++ assert lifecycle.register_kwargs["preconfigured"] is False+++class TestMarkingAnExistingBridge:+ async def test_it_is_stored_returned_and_told_to_the_running_bridge(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ bridge_id = await _make_bridge(session)+ await session.commit()+ lifecycle = _Lifecycle()++ async with session_factory() as session:+ detail = await update_bridge(+ bridge_id,+ BridgeUpdateRequest(preconfigured=True),+ session,+ _BRIDGE_STORE,+ _ROOM_STORE,+ lifecycle, # type: ignore[arg-type]+ _admin(),+ )++ assert detail.preconfigured is True+ assert lifecycle.noted == [(bridge_id, True)]+ # Marking it changes no connection setting, so the bridge keeps running.+ assert lifecycle.restarted == []+ async with session_factory() as session:+ stored = await _BRIDGE_STORE.get(session, bridge_id)+ assert stored is not None and stored.preconfigured is True++ async def test_an_update_that_does_not_mention_it_leaves_it_alone(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ bridge_id = await _make_bridge(session)+ await _BRIDGE_STORE.set_preconfigured(session, bridge_id, True)+ await session.commit()+ lifecycle = _Lifecycle()++ async with session_factory() as session:+ detail = await update_bridge(+ bridge_id,+ BridgeUpdateRequest(agent_greetings_enabled=False),+ session,+ _BRIDGE_STORE,+ _ROOM_STORE,+ lifecycle, # type: ignore[arg-type]+ _admin(),+ )++ assert detail.preconfigured is True+ assert lifecycle.noted == []+++class TestReadingItBack:+ async def test_the_listing_says_which_bridges_are_preconfigured(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """What the setup step reads to decide whether it still has to mark+ one. A bridge that predates the column reads as not preconfigured."""+ async with session_factory() as session:+ bundled = await _make_bridge(session)+ added = await _make_bridge(session)+ await _BRIDGE_STORE.set_preconfigured(session, bundled, True)+ await session.commit()++ async with session_factory() as session:+ listed = await list_bridges(+ session,+ _BRIDGE_STORE,+ _ROOM_STORE,+ _NoRunningBridges(), # type: ignore[arg-type]+ _admin(),+ )++ flags = {d.bridge_id: d.preconfigured for d in listed}+ assert flags[bundled] is True+ assert flags[added] is Falsediff --git a/core/tests/switch_core/session_activity/test_session_started_route.py b/core/tests/switch_core/session_activity/test_session_started_route.pynew file mode 100644index 000000000..c0134df7b--- /dev/null+++ b/core/tests/switch_core/session_activity/test_session_started_route.py@@ -0,0 +1,311 @@+"""A session host reporting that a session started, and how.++The only way the server learns who started a session: sessions share their+agent's one connection, so nothing about a new one reaches the server unless+the host that runs it says so.+"""++from __future__ import annotations++import uuid+from typing import get_args++import httpx+import pytest+from fastapi import FastAPI++from switch_core.bridges.agent.api.activity_routes import router+from switch_core.bridges.agent.auth import get_agent_from_scope+from switch_core.bridges.agent.dependencies import (+ get_session_factory,+ get_session_start_limiter,+ get_telemetry,+)+from switch_core.db.models import Agent+from switch_core.telemetry.catalogue import CATALOGUE+from switch_core.telemetry.service import TelemetryService+from switch_core.telemetry.session_start import (+ SessionStartLimiter,+ StartSource,+ default_session_start_limiter,+)+from switch_core.telemetry.sink import TelemetryRecord++# What every launcher mints: a random v4 from Console, or a v5-shaped hash from+# the room watcher.+SESSION = "0f8fad5b-d9cb-469f-a165-70867728950e"+++class _RecordingSink:+ def __init__(self) -> None:+ self.sent: list[TelemetryRecord] = []++ async def send(self, record: TelemetryRecord) -> None:+ self.sent.append(record)++ async def aclose(self) -> None:+ return None+++def _telemetry(sink: _RecordingSink, *, enabled: bool) -> TelemetryService:+ return TelemetryService(+ sink=sink, # type: ignore[arg-type]+ enabled=enabled,+ client_id="11111111-1111-1111-1111-111111111111",+ service_name="switch-core",+ version=None,+ environment=None,+ )+++def _app(+ session_factory,+ telemetry: TelemetryService | None,+ agent: Agent,+ limiter: SessionStartLimiter | None = None,+) -> FastAPI:+ app = FastAPI()+ app.include_router(router)+ app.dependency_overrides[get_session_factory] = lambda: session_factory+ app.dependency_overrides[get_agent_from_scope] = lambda: agent+ app.dependency_overrides[get_telemetry] = lambda: telemetry+ chosen = limiter or default_session_start_limiter()+ app.dependency_overrides[get_session_start_limiter] = lambda: chosen+ return app+++def _agent(runtime: str = "codex") -> Agent:+ return Agent(+ id=f"agent-{uuid.uuid4().hex[:8]}", metadata_={"known_agent_type": runtime}+ )+++async def _post(app: FastAPI, session_id: str, body: object) -> httpx.Response:+ async with httpx.AsyncClient(+ transport=httpx.ASGITransport(app=app), base_url="http://test"+ ) as http:+ return await http.post(f"/agent-sessions/{session_id}/started", json=body)+++def _started(sink: _RecordingSink) -> list[dict[str, object]]:+ return [+ dict(r.properties) for r in sink.sent if r.name == "switch_core.session_started"+ ]+++async def test_a_new_session_is_reported_with_how_it_started(session_factory) -> None:+ sink = _RecordingSink()+ telemetry = _telemetry(sink, enabled=True)+ app = _app(session_factory, telemetry, _agent("claude-code"))++ response = await _post(app, SESSION, {"start_source": "user"})+ await telemetry.aclose()++ assert (response.status_code, response.json()) == (200, {"reported": True})+ assert _started(sink) == [+ {"start_source": "user", "known_agent_type": "claude-code"}+ ]+++async def test_reporting_the_same_session_again_counts_once(session_factory) -> None:+ """A host retries until the server answers, so an answer lost on the way+ back arrives as a second report of the same start."""+ sink = _RecordingSink()+ telemetry = _telemetry(sink, enabled=True)+ app = _app(session_factory, telemetry, _agent())++ first = await _post(app, SESSION, {"start_source": "room"})+ again = await _post(app, SESSION, {"start_source": "room"})+ await telemetry.aclose()++ assert first.json() == {"reported": True}+ assert again.json() == {"reported": False}+ assert len(_started(sink)) == 1+++async def test_two_agents_with_the_same_session_id_each_count(session_factory) -> None:+ sink = _RecordingSink()+ telemetry = _telemetry(sink, enabled=True)++ await _post(+ _app(session_factory, telemetry, _agent()),+ SESSION,+ {"start_source": "user"},+ )+ await _post(+ _app(session_factory, telemetry, _agent()),+ SESSION,+ {"start_source": "user"},+ )+ await telemetry.aclose()++ assert len(_started(sink)) == 2+++async def test_nothing_is_sent_or_claimed_while_telemetry_is_off(+ session_factory,+) -> None:+ """Switching telemetry on later must still count a session reported+ while it was off — here, the same host retrying after the switch."""+ agent = _agent()+ off_sink = _RecordingSink()+ off = _telemetry(off_sink, enabled=False)+ on_sink = _RecordingSink()+ on = _telemetry(on_sink, enabled=True)++ while_off = await _post(+ _app(session_factory, off, agent), SESSION, {"start_source": "user"}+ )+ once_on = await _post(+ _app(session_factory, on, agent), SESSION, {"start_source": "user"}+ )+ await off.aclose()+ await on.aclose()++ assert while_off.json() == {"reported": False}+ assert _started(off_sink) == []+ assert once_on.json() == {"reported": True}+++async def test_a_server_with_no_telemetry_service_answers_rather_than_failing(+ session_factory,+) -> None:+ response = await _post(+ _app(session_factory, None, _agent()), SESSION, {"start_source": "user"}+ )++ assert (response.status_code, response.json()) == (200, {"reported": False})+++ "body",+ [+ {"start_source": "console"},+ {"start_source": None},+ {},+ {"start_source": "user", "unexpected": 1},+ ],+)+async def test_a_source_outside_the_set_is_refused(session_factory, body) -> None:+ """The value goes straight into a telemetry property, so it is held to the+ catalogue here rather than trusted."""+ sink = _RecordingSink()+ telemetry = _telemetry(sink, enabled=True)++ response = await _post(_app(session_factory, telemetry, _agent()), SESSION, body)+ await telemetry.aclose()++ assert response.status_code == 422+ assert _started(sink) == []++[email protected]("start_source", get_args(StartSource))+async def test_every_source_the_route_accepts_is_sent(+ session_factory, start_source+) -> None:+ """The route spends the once-only claim before it emits. A value it accepts+ that the catalogue refuses would be claimed, dropped by the emitter, and+ answered `reported: true` — lost for good with nothing saying so."""+ sink = _RecordingSink()+ telemetry = _telemetry(sink, enabled=True)++ response = await _post(+ _app(session_factory, telemetry, _agent()),+ SESSION,+ {"start_source": start_source},+ )+ await telemetry.aclose()++ assert response.json() == {"reported": True}+ assert [e["start_source"] for e in _started(sink)] == [start_source]+++def test_the_route_and_the_catalogue_accept_the_same_sources() -> None:+ declared = CATALOGUE["session_started"]["start_source"]+ assert set(get_args(StartSource)) == set(declared.values) # type: ignore[attr-defined]++[email protected]("session_id", ["session-1", "s" * 201, "not-a-uuid-at-all"])+async def test_a_session_id_that_is_not_a_uuid_is_refused(+ session_factory, session_id+) -> None:+ """Every launcher mints UUIDs. Anything else is a caller making ids up,+ and each one would be another claim row."""+ sink = _RecordingSink()+ telemetry = _telemetry(sink, enabled=True)++ response = await _post(+ _app(session_factory, telemetry, _agent()), session_id, {"start_source": "user"}+ )+ await telemetry.aclose()++ assert response.status_code == 422+ assert _started(sink) == []+++class _Clock:+ def __init__(self) -> None:+ self.now = 0.0++ def __call__(self) -> float:+ return self.now+++async def test_an_agent_past_its_cap_is_not_counted(session_factory, caplog) -> None:+ """One agent inventing sessions cannot fill the table or the chart."""+ sink = _RecordingSink()+ telemetry = _telemetry(sink, enabled=True)+ limiter = SessionStartLimiter(max_per_window=2, window_seconds=3600, clock=_Clock())+ app = _app(session_factory, telemetry, _agent(), limiter)++ answers = [+ (await _post(app, str(uuid.uuid4()), {"start_source": "user"})).json()+ for _ in range(3)+ ]+ await telemetry.aclose()++ assert answers == [{"reported": True}, {"reported": True}, {"reported": False}]+ assert len(_started(sink)) == 2+ assert "more than 2 session starts" in caplog.text+++async def test_the_cap_is_per_agent(session_factory) -> None:+ sink = _RecordingSink()+ telemetry = _telemetry(sink, enabled=True)+ limiter = SessionStartLimiter(max_per_window=1, window_seconds=3600, clock=_Clock())+ busy, other = _agent(), _agent()++ await _post(+ _app(session_factory, telemetry, busy, limiter),+ str(uuid.uuid4()),+ {"start_source": "user"},+ )+ capped = await _post(+ _app(session_factory, telemetry, busy, limiter),+ str(uuid.uuid4()),+ {"start_source": "user"},+ )+ unaffected = await _post(+ _app(session_factory, telemetry, other, limiter),+ str(uuid.uuid4()),+ {"start_source": "user"},+ )+ await telemetry.aclose()++ assert capped.json() == {"reported": False}+ assert unaffected.json() == {"reported": True}+++async def test_the_cap_lifts_once_the_window_has_passed(session_factory) -> None:+ sink = _RecordingSink()+ telemetry = _telemetry(sink, enabled=True)+ clock = _Clock()+ limiter = SessionStartLimiter(max_per_window=1, window_seconds=3600, clock=clock)+ app = _app(session_factory, telemetry, _agent(), limiter)++ await _post(app, str(uuid.uuid4()), {"start_source": "user"})+ clock.now = 3600.0+ later = await _post(app, str(uuid.uuid4()), {"start_source": "user"})+ await telemetry.aclose()++ assert later.json() == {"reported": True}diff --git a/core/tests/switch_core/telemetry/test_bridge_connect_reporting.py b/core/tests/switch_core/telemetry/test_bridge_connect_reporting.pyindex 28a3fcf54..e93b53b5a 100644--- a/core/tests/switch_core/telemetry/test_bridge_connect_reporting.py+++ b/core/tests/switch_core/telemetry/test_bridge_connect_reporting.py@@ -23,6 +23,7 @@ both unaffected by telemetry being added.from __future__ import annotationsimport uuid+from datetime import datetimefrom typing import Anyfrom unittest.mock import AsyncMock, MagicMock@@ -67,6 +68,7 @@ def _service_with_telemetry(*,callback_port: int = 0,client_store: Any = None,+ installed_at: datetime | None = None,) -> tuple[CollaborationBridgeLifecycleService, _RecordingSink]:sink = _RecordingSink()telemetry = TelemetryService(@@ -77,6 +79,7 @@ def _service_with_telemetry(version=None,environment=None,session_factory=session_factory,+ installed_at=installed_at,)config = MagicMock()config.gateway_public_url = "https://gw.example"diff --git a/core/tests/switch_core/telemetry/test_emitters_are_live.py b/core/tests/switch_core/telemetry/test_emitters_are_live.pyindex 1feba4318..97d5ba50e 100644--- a/core/tests/switch_core/telemetry/test_emitters_are_live.py+++ b/core/tests/switch_core/telemetry/test_emitters_are_live.py@@ -24,7 +24,7 @@ from __future__ import annotationsfrom typing import Anyfrom switch_core.bridges.agent.app import create_agent_bridge_app-from switch_core.bridges.agent.dependencies import get_protocol+from switch_core.bridges.agent.dependencies import get_protocol, get_telemetryfrom switch_core.bridges.agent.protocol.event_buffer import EventBufferfrom switch_core.telemetry.service import TelemetryServicefrom switch_core.telemetry.sink import NullSink@@ -104,3 +104,13 @@ def test_the_protocol_service_the_app_returns_is_the_one_handlers_use() -> None:"other — which is how the session events came to be emitted into ""nothing.")+++def test_the_session_start_route_reaches_the_same_telemetry() -> None:+ """`/agent-sessions/{id}/started` resolves telemetry on its own rather than+ through the protocol service. Wired to nothing, it answers every host+ with `reported: false` and no error anywhere."""+ telemetry = _telemetry()+ _build(telemetry)++ assert get_telemetry() is telemetrydiff --git a/core/tests/switch_core/telemetry/test_preconfigured_connectors.py b/core/tests/switch_core/telemetry/test_preconfigured_connectors.pynew file mode 100644index 000000000..0f64ff0ed--- /dev/null+++ b/core/tests/switch_core/telemetry/test_preconfigured_connectors.py@@ -0,0 +1,297 @@+"""A connector the deployment registered itself is not a person onboarding.++The standalone stack, the Helm chart and every Console-managed local server run+a setup step that registers the bundled Mattermost seconds after install. Left+alone, that connector claims `first_connector_added` on every such deployment,+so "time to first connector" reads as boot time and the connector a person+actually added later is never a milestone at all.+"""++from __future__ import annotations++import uuid+from datetime import UTC, datetime, timedelta+from types import SimpleNamespace+from typing import Any+from unittest.mock import AsyncMock, MagicMock++import pytest+from sqlalchemy import update+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.bridges.collaboration.lifecycle_service import (+ CollaborationBridgeLifecycleService,+)+from switch_core.db.models import CollaborationBridge+from switch_core.telemetry.deployment import claim_milestone+from switch_core.telemetry.service import TelemetryService+from tests.switch_core.bridges.collaboration.test_lifecycle_tenant_binding import (+ _make_bridge,+ _make_tenant,+ _StubAdapter,+ _StubConfig,+)+from tests.switch_core.bridges.collaboration.test_teams_zero_config import (+ _lifecycle,+ _RecordingAdapter,+)+from tests.switch_core.telemetry.test_bridge_connect_reporting import (+ _RecordingSink,+ _service_with_telemetry,+)++INSTALLED = datetime.now(UTC) - timedelta(minutes=5)+++def _running(+ service: CollaborationBridgeLifecycleService,+ bridge_id: str,+ *,+ preconfigured: bool,+) -> None:+ """What `start()` records for a bridge before it connects."""+ service._bridges[bridge_id] = MagicMock()+ if preconfigured:+ service._preconfigured.add(bridge_id)+++async def _events(+ service: CollaborationBridgeLifecycleService, sink: _RecordingSink, name: str+) -> list[dict[str, Any]]:+ await service._telemetry.aclose() # type: ignore[union-attr]+ return [+ dict(record.properties)+ for record in sink.sent+ if record.name == f"switch_core.{name}"+ ]+++class TestTheBundledConnector:+ async def test_it_reports_itself_as_preconfigured(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ service, sink = _service_with_telemetry(session_factory, installed_at=INSTALLED)+ bundled = f"bundled-{uuid.uuid4().hex[:8]}"+ _running(service, bundled, preconfigured=True)++ await service._report_connector_up(bundled, "mattermost", INSTALLED)++ [added] = await _events(service, sink, "connector_added")+ assert added["is_preconfigured"] is True+ assert added["is_first_connector"] is False++ async def test_it_does_not_claim_the_first_connector_milestone(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ service, sink = _service_with_telemetry(session_factory, installed_at=INSTALLED)+ bundled = f"bundled-{uuid.uuid4().hex[:8]}"+ _running(service, bundled, preconfigured=True)++ await service._report_connector_up(bundled, "mattermost", INSTALLED)++ assert await _events(service, sink, "first_connector_added") == []++ async def test_reconnecting_later_still_does_not_claim_it(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The path taken once this bridge's own claim is spent, on every+ restart after the first."""+ service, sink = _service_with_telemetry(session_factory, installed_at=INSTALLED)+ bundled = f"bundled-{uuid.uuid4().hex[:8]}"+ _running(service, bundled, preconfigured=True)++ await service._report_connector_up(bundled, "mattermost", INSTALLED)+ await service._report_connector_up(bundled, "mattermost", INSTALLED)++ assert await _events(service, sink, "first_connector_added") == []+++class TestTheConnectorAPersonAdds:+ async def test_it_is_the_first_connector_despite_the_bundled_one(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ service, sink = _service_with_telemetry(session_factory, installed_at=INSTALLED)+ bundled = f"bundled-{uuid.uuid4().hex[:8]}"+ slack = f"slack-{uuid.uuid4().hex[:8]}"+ _running(service, bundled, preconfigured=True)+ await service._report_connector_up(bundled, "mattermost", INSTALLED)+ _running(service, slack, preconfigured=False)++ await service._report_connector_up(slack, "slack", INSTALLED)++ added = await _events(service, sink, "connector_added")+ assert [(a["bridge_platform"], a["is_first_connector"]) for a in added] == [+ ("mattermost", False),+ ("slack", True),+ ]+ assert added[1]["is_preconfigured"] is False++ async def test_it_claims_the_first_connector_milestone(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ service, sink = _service_with_telemetry(session_factory, installed_at=INSTALLED)+ bundled = f"bundled-{uuid.uuid4().hex[:8]}"+ slack = f"slack-{uuid.uuid4().hex[:8]}"+ _running(service, bundled, preconfigured=True)+ await service._report_connector_up(bundled, "mattermost", INSTALLED)+ _running(service, slack, preconfigured=False)++ await service._report_connector_up(slack, "slack", INSTALLED)++ [milestone] = await _events(service, sink, "first_connector_added")+ assert milestone["bridge_platform"] == "slack"++ async def test_it_still_claims_the_milestone_once_its_own_report_is_spent(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """A connector whose own `connector_added` went out before this+ deployment had an install clock: the deployment-wide milestone may+ still be unclaimed, and a person's connector is what claims it."""+ service, sink = _service_with_telemetry(session_factory, installed_at=INSTALLED)+ slack = f"slack-{uuid.uuid4().hex[:8]}"+ assert await claim_milestone(session_factory, f"connector_added:{slack}")+ _running(service, slack, preconfigured=False)++ await service._report_connector_up(slack, "slack", INSTALLED)++ assert await _events(service, sink, "connector_added") == []+ [milestone] = [+ dict(r.properties)+ for r in sink.sent+ if r.name == "switch_core.first_connector_added"+ ]+ assert milestone["bridge_platform"] == "slack"++ async def test_a_second_one_is_not_the_first(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ service, sink = _service_with_telemetry(session_factory, installed_at=INSTALLED)+ slack = f"slack-{uuid.uuid4().hex[:8]}"+ teams = f"teams-{uuid.uuid4().hex[:8]}"+ _running(service, slack, preconfigured=False)+ await service._report_connector_up(slack, "slack", INSTALLED)+ _running(service, teams, preconfigured=False)++ await service._report_connector_up(teams, "teams", INSTALLED)++ added = await _events(service, sink, "connector_added")+ assert [a["is_first_connector"] for a in added] == [True, False]+++class TestTheFlagIsReadOffTheRow:+ async def test_start_records_a_preconfigured_bridge(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ tenant = f"tenant-{uuid.uuid4().hex[:8]}"+ async with session_factory() as session:+ await _make_tenant(session, tenant)+ bridge_id, _ = await _make_bridge(session, tenant_id=tenant)+ await session.execute(+ update(CollaborationBridge)+ .where(CollaborationBridge.id == bridge_id)+ .values(preconfigured=True)+ )+ await session.commit()++ service, _ = _service_with_telemetry(session_factory)+ service.register_adapter("mattermost", _StubAdapter, _StubConfig)+ service._run_bridge = AsyncMock() # type: ignore[method-assign]++ await service.start(bridge_id)++ assert bridge_id in service._preconfigured++ async def test_start_does_not_record_a_bridge_a_person_added(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ tenant = f"tenant-{uuid.uuid4().hex[:8]}"+ async with session_factory() as session:+ await _make_tenant(session, tenant)+ bridge_id, _ = await _make_bridge(session, tenant_id=tenant)+ await session.commit()++ service, _ = _service_with_telemetry(session_factory)+ service.register_adapter("mattermost", _StubAdapter, _StubConfig)+ service._run_bridge = AsyncMock() # type: ignore[method-assign]+ # Left over from an earlier start, before the row was changed back.+ service._preconfigured.add(bridge_id)++ await service.start(bridge_id)++ assert bridge_id not in service._preconfigured+++class TestMarkingARunningBridge:+ """The setup step marks a bridge it registered before the flag existed,+ after the bridge is already running. A connector a person adds before the+ next restart must not see it as a person's."""++ def test_a_running_bridge_follows_the_change(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ service, _ = _service_with_telemetry(session_factory)+ service._bridge_facts["bundled"] = ("mattermost", INSTALLED)++ service.note_preconfigured("bundled", True)+ assert "bundled" in service._preconfigured++ service.note_preconfigured("bundled", False)+ assert "bundled" not in service._preconfigured++ def test_a_bridge_that_is_not_running_is_not_tracked(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """It reads the row when it starts; tracking it here would leave an+ entry nothing ever removes."""+ service, _ = _service_with_telemetry(session_factory)++ service.note_preconfigured("stopped", True)++ assert "stopped" not in service._preconfigured+++class TestRegisteringRecordsTheFlag:+ """What the setup step asked for is what the row holds, and what the+ configured event says."""++ @pytest.mark.parametrize("preconfigured", [True, False])+ async def test_the_row_and_connector_configured_carry_it(+ self, session_factory: async_sessionmaker[AsyncSession], preconfigured: bool+ ) -> None:+ _RecordingAdapter.events = []+ _RecordingAdapter.fail_verification = False+ service = _lifecycle()+ sink = _RecordingSink()+ service._telemetry = TelemetryService(+ sink=sink, # type: ignore[arg-type]+ enabled=True,+ client_id="deployment-uuid",+ service_name="switch-core",+ version=None,+ environment=None,+ )+ service._session_factory = session_factory+ service._client_lifecycle.create_client = AsyncMock( # type: ignore[method-assign]+ return_value=SimpleNamespace(id="bridge-client")+ )+ stored: list[CollaborationBridge] = []+ service._bridge_store.create = AsyncMock( # type: ignore[method-assign]+ side_effect=lambda session, bridge: stored.append(bridge)+ )+ service.start = AsyncMock() # type: ignore[method-assign]++ await service.register(+ bridge_type="recording",+ display_name="Recording",+ connection_config={"app_id": "a"},+ channel_creation_enabled=False,+ preconfigured=preconfigured,+ )++ [row] = stored+ assert row.preconfigured is preconfigured+ [configured] = await _events(service, sink, "connector_configured")+ assert configured == {+ "bridge_platform": "none",+ "is_preconfigured": preconfigured,+ }diff --git a/core/tests/switch_core/telemetry/test_session_start_prune.py b/core/tests/switch_core/telemetry/test_session_start_prune.pynew file mode 100644index 000000000..8633e990f--- /dev/null+++ b/core/tests/switch_core/telemetry/test_session_start_prune.py@@ -0,0 +1,119 @@+"""Session start claims are kept only as long as they are useful.++They share `telemetry_milestones` with claims that must never go — a once-ever+milestone or a connector's first connect, which pruning would report again —+so the prune is held to its own rows by name and by age.+"""++from __future__ import annotations++from datetime import UTC, datetime, timedelta++import pytest+from sqlalchemy import delete, select+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.db.models import TelemetryMilestone, TelemetrySnapshotWatermark+from switch_core.telemetry import reporter as reporter_module+from switch_core.telemetry.session_start import CLAIM_TTL, prune_session_start_claims+from tests.switch_core.telemetry.test_deployment_and_reporter import (+ TestTheSnapshotSchedule,+ _RecordingSink,+)++NOW = datetime(2026, 9, 29, 12, 0, tzinfo=UTC)+OLD = NOW - CLAIM_TTL - timedelta(hours=1)+RECENT = NOW - timedelta(days=1)+++async def _claims(+ session_factory: async_sessionmaker[AsyncSession], rows: dict[str, datetime]+) -> None:+ async with session_factory() as session:+ await session.execute(delete(TelemetryMilestone))+ session.add_all(+ TelemetryMilestone(name=name, emitted_at=when)+ for name, when in rows.items()+ )+ await session.commit()+++async def _left(session_factory: async_sessionmaker[AsyncSession]) -> set[str]:+ async with session_factory() as session:+ return set((await session.execute(select(TelemetryMilestone.name))).scalars())+++async def test_it_removes_only_session_claims_past_their_use(+ session_factory: async_sessionmaker[AsyncSession],+) -> None:+ await _claims(+ session_factory,+ {+ "session_started:agent-1:old": OLD,+ "session_started:agent-1:recent": RECENT,+ # Never pruned, however old: each would be reported again.+ "connector_added:bridge-1": OLD,+ "first_connector_added": OLD,+ "first_session_started": OLD,+ },+ )++ pruned = await prune_session_start_claims(session_factory, now=NOW)++ assert pruned == 1+ assert await _left(session_factory) == {+ "session_started:agent-1:recent",+ "connector_added:bridge-1",+ "first_connector_added",+ "first_session_started",+ }+++async def test_the_prefix_is_matched_literally(+ session_factory: async_sessionmaker[AsyncSession],+) -> None:+ """An underscore is a wildcard to LIKE. Matched unescaped, a name that+ merely resembles the prefix would be deleted with the claims."""+ await _claims(session_factory, {"sessionXstarted:agent-1:old": OLD})++ assert await prune_session_start_claims(session_factory, now=NOW) == 0+ assert await _left(session_factory) == {"sessionXstarted:agent-1:old"}+++class TestItRunsWithTheDailySnapshot:+ async def test_a_snapshot_pass_prunes_old_claims(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ await session.execute(delete(TelemetrySnapshotWatermark))+ await session.commit()+ stale = datetime.now(UTC) - CLAIM_TTL - timedelta(hours=1)+ await _claims(session_factory, {"session_started:agent-1:old": stale})+ reporter = TestTheSnapshotSchedule()._reporter(+ _RecordingSink(), session_factory+ )++ assert await reporter.run_once_if_due() is True++ assert await _left(session_factory) == set()++ async def test_a_failed_prune_does_not_send_the_snapshot_again(+ self,+ session_factory: async_sessionmaker[AsyncSession],+ monkeypatch: pytest.MonkeyPatch,+ ) -> None:+ async with session_factory() as session:+ await session.execute(delete(TelemetrySnapshotWatermark))+ await session.commit()++ async def broken(*args: object, **kwargs: object) -> int:+ raise RuntimeError("database went away")++ monkeypatch.setattr(reporter_module, "prune_session_start_claims", broken)+ sink = _RecordingSink()+ reporter = TestTheSnapshotSchedule()._reporter(sink, session_factory)++ assert await reporter.run_once_if_due() is True+ # The watermark was written before the prune failed, so the next+ # poll finds nothing due rather than sending the snapshot again.+ assert await reporter.run_once_if_due() is Falsediff --git a/core/tests/switch_core/telemetry/test_snapshot.py b/core/tests/switch_core/telemetry/test_snapshot.pyindex 5642be87e..005f8a035 100644--- a/core/tests/switch_core/telemetry/test_snapshot.py+++ b/core/tests/switch_core/telemetry/test_snapshot.py@@ -17,6 +17,8 @@ from datetime import UTC, datetime, timedeltafrom sqlalchemy import deletefrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker+from switch_core.clients.admin_messages import AUTO_REPLY_FLAG+from switch_core.clients.client_base import ClientBasefrom switch_core.db.models import (Agent,ApiKey,@@ -27,7 +29,9 @@ from switch_core.db.models import (Room,User,)+from switch_core.messages.recorded_types import MEMBERSHIP_EVENT_TYPEfrom switch_core.telemetry.snapshot import (+ SPOKEN_EVENT_TYPES,UsageCounts,collect_tenant_counts,collect_usage,@@ -154,6 +158,57 @@ async def _say(return message+async def _stored(+ session: AsyncSession,+ room: Room,+ sender: Client,+ *,+ seq: int,+ event_type: str,+ content: dict[str, object],+ when: datetime | None = None,+) -> None:+ """A row the transport writes that is not a chat message: an arrival, a+ tool-call report, a task transition. Every durable event gets one."""+ session.add(+ Message(+ room_id=room.id,+ seq=seq,+ transport_event_id=f"$evt-{uuid.uuid4().hex}",+ sender_id=sender.matrix_user_id,+ sender_client_id=sender.id,+ event_type=event_type,+ msgtype=None,+ body=None,+ content=content,+ sent_at=when or (NOW - timedelta(hours=1)),+ )+ )+ await session.flush()+++async def _arrive(+ session: AsyncSession,+ room: Room,+ client: Client,+ *,+ seq: int,+ when: datetime | None = None,+) -> None:+ """Join the room the way the transport does: a membership row and a+ message-log row, not only the former."""+ await _join(session, client, room)+ await _stored(+ session,+ room,+ client,+ seq=seq,+ event_type="m.room.member",+ content={"membership": "join", "displayname": client.display_name},+ when=when,+ )++TENANT_ZERO = "00000000-0000-0000-0000-000000000000"@@ -412,6 +467,200 @@ class TestMessageCounts:assert counts.message_count_1d == 0+class TestOnlyWhatSomeoneSaidCounts:+ """The message log holds every durable event, not only the conversation.+ An agent joining a room or reporting a tool call is not an agent message,+ and a person being added to a room is not that person using it."""++ async def test_agent_arrivals_and_reports_are_not_agent_messages(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _room(session)+ agent = await _client(session, "agent")+ await _arrive(session, room, agent, seq=1)+ await _stored(+ session,+ room,+ agent,+ seq=2,+ event_type="com.switch.report.tool_call",+ content={"agent_id": "a", "tool_id": "Bash"},+ )+ await _stored(+ session,+ room,+ agent,+ seq=3,+ event_type="com.switch.task.update",+ content={"task_id": "t", "status": "working"},+ )++ counts = await _counts(session)++ assert counts.message_count_1d == 0+ assert counts.message_from_agent_1d == 0+ assert counts.agent_active_7d == 0++ async def test_a_person_added_to_a_room_is_not_active_in_it(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _room(session)+ agent = await _client(session, "agent")+ human = await _client(session, "user")+ await _join(session, agent, room)+ await _arrive(session, room, human, seq=1)++ counts = await _counts(session)+ ever_active = await room_had_human_activity(session, TENANT_ZERO, room.id)++ assert counts.message_from_human_1d == 0+ assert counts.user_active_1d == 0+ assert counts.user_active_7d == 0+ assert counts.room_active_1d == 0+ assert counts.room_active_7d == 0+ assert ever_active is False++ async def test_a_command_a_person_typed_is_something_they_said(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _room(session)+ agent = await _client(session, "agent")+ human = await _client(session, "user")+ await _join(session, agent, room)+ await _join(session, human, room)+ await _stored(+ session,+ room,+ human,+ seq=1,+ event_type="com.switch.command",+ content={"command": "reset", "args": ""},+ )++ counts = await _counts(session)++ assert counts.message_from_human_1d == 1+ assert counts.user_active_1d == 1+ assert counts.room_active_1d == 1++ async def test_the_notice_switch_posts_for_an_agent_is_not_the_agent_talking(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Addressed while it has no session, an agent "replies" with an+ automatic notice. Counted, every unavailable agent reads as a+ responsive one."""+ async with session_factory() as session:+ room = await _room(session)+ agent = await _client(session, "agent")+ human = await _client(session, "user")+ await _say(session, room, human, seq=1)+ await _stored(+ session,+ room,+ agent,+ seq=2,+ event_type="m.room.message",+ content={+ "msgtype": "m.notice",+ "body": "no session; starting one",+ AUTO_REPLY_FLAG: True,+ },+ )++ counts = await _counts(session)++ assert counts.message_count_1d == 1+ assert counts.message_from_agent_1d == 0+ assert counts.agent_active_7d == 0+ assert counts.turn_human_to_agent_1d == 0++ async def test_a_person_added_to_a_room_does_not_activate_it(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _room(session, created_at=NOW - timedelta(hours=5))+ agent = await _client(session, "agent")+ human = await _client(session, "user")+ await _join(session, agent, room)+ await _arrive(session, room, human, seq=1, when=NOW - timedelta(hours=1))+ await session.commit()++ found = await newly_active_rooms(+ session_factory, since=NOW - timedelta(hours=4), now=NOW+ )++ assert found == []++ async def test_a_room_activates_when_the_person_speaks_not_when_they_arrived(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Added before the window and speaking inside it is a room first used+ inside it. Read off the arrival, it would have looked already active+ and never been reported at all."""+ async with session_factory() as session:+ room = await _room(session, created_at=NOW - timedelta(days=2))+ agent = await _client(session, "agent")+ human = await _client(session, "user")+ await _join(session, agent, room)+ await _arrive(session, room, human, seq=1, when=NOW - timedelta(days=1))+ await _say(session, room, human, seq=2, when=NOW - timedelta(hours=1))+ await session.commit()++ found = await newly_active_rooms(+ session_factory, since=NOW - timedelta(hours=4), now=NOW+ )++ assert len(found) == 1++ async def test_an_agent_that_arrived_and_left_still_makes_it_an_agent_room(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Deliberately not narrowed to what agents said: its arrival row is the+ durable record that an agent was there, which its membership is not+ once it is removed."""+ async with session_factory() as session:+ room = await _room(session)+ agent = await _client(session, "agent")+ human = await _client(session, "user")+ await _stored(+ session,+ room,+ agent,+ seq=1,+ event_type=MEMBERSHIP_EVENT_TYPE,+ content={"membership": "join", "displayname": "agent"},+ )+ await _say(session, room, human, seq=2)++ counts = await _counts(session)++ assert counts.room_active_1d == 1++ async def test_a_turn_pairs_across_rows_that_are_not_messages(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """A second agent arriving between a question and its answer must not+ be what the answer is paired with: that would read as one+ human-to-agent turn from the arrival and one agent-to-agent turn from+ the answer."""+ async with session_factory() as session:+ room = await _room(session)+ human = await _client(session, "user")+ answering = await _client(session, "agent")+ arriving = await _client(session, "agent")+ await _say(session, room, human, seq=1)+ await _arrive(session, room, arriving, seq=2)+ await _say(session, room, answering, seq=3)++ counts = await _counts(session)++ assert counts.turn_human_to_agent_1d == 1+ assert counts.turn_agent_to_agent_1d == 0++class TestAgentsAndConnectors:async def test_agents_are_split_by_runtime(self, session_factory: async_sessionmaker[AsyncSession]@@ -920,3 +1169,37 @@ class TestATurnNeedsTwoParticipants:counts = await _counts(session)assert counts.turn_agent_to_human_1d == 1+++# Stored in the message log, and not something a participant said.+NOT_SPOKEN = frozenset(+ {+ MEMBERSHIP_EVENT_TYPE, # an arrival+ "com.switch.report.tool_call", # measurements of a run+ "com.switch.report.llm_call",+ "com.switch.task.delegate", # task transitions+ "com.switch.task.accept",+ "com.switch.task.update",+ "com.switch.task.finalise",+ "com.switch.task.cancel",+ "com.switch.agent.runtime_state", # presence; never stored+ }+)+++def test_every_event_type_is_decided_spoken_or_not() -> None:+ """A new room event type lands in the message log by default. Undecided,+ it would either inflate the message counts or be silently left out of+ them; this makes whoever adds one say which."""+ known = set(ClientBase._EVENT_DISPATCH) | {"m.room.message", MEMBERSHIP_EVENT_TYPE}+ spoken = set(SPOKEN_EVENT_TYPES)++ assert not (known - spoken - NOT_SPOKEN), (+ "Decide whether these count as something a participant said, in "+ "SPOKEN_EVENT_TYPES in telemetry/snapshot.py or NOT_SPOKEN here: "+ f"{sorted(known - spoken - NOT_SPOKEN)}"+ )+ assert not (spoken & NOT_SPOKEN)+ assert not (NOT_SPOKEN - known), (+ f"No longer an event type: {sorted(NOT_SPOKEN - known)}"+ )diff --git a/deploy/shared_resources/setup.py b/deploy/shared_resources/setup.pyindex 334c7c7cf..4cba067e4 100644--- a/deploy/shared_resources/setup.py+++ b/deploy/shared_resources/setup.py@@ -255,6 +255,18 @@ def register_bridge(client: httpx.Client) -> str:f"/gateway/collaborations/{bridge_id}/default").raise_for_status()print(f"Set Mattermost bridge as default: {bridge_id}")+ # And mark it as the deployment's own, for a bridge registered+ # before the flag existed. Telemetry leaves a preconfigured+ # connector out of onboarding: it came up because the deployment+ # booted, not because anybody connected anything. A server that+ # predates the flag does not list it, and is left alone rather+ # than sent a field it would ignore.+ if bridge.get("preconfigured") is False:+ client.patch(+ f"/gateway/collaborations/{bridge_id}",+ json={"preconfigured": True},+ ).raise_for_status()+ print(f"Marked Mattermost bridge as preconfigured: {bridge_id}")# Same reason: a bridge registered before callbacks existed# would otherwise keep drawing cards with no buttons on them,# and the only cure would be editing a connection field by@@ -300,6 +312,9 @@ def register_bridge(client: httpx.Client) -> str:# The bundled Mattermost is the deployment's own chat, so it is# what rooms should bridge to when the caller names nothing."set_as_default": True,+ # Registered by this step, not by a person, so it is not counted+ # as anyone connecting a platform.+ "preconfigured": True,},)resp.raise_for_status()diff --git a/docs/old/telemetry-events.md b/docs/old/telemetry-events.mdindex a80f7f4a0..a429097a0 100644--- a/docs/old/telemetry-events.md+++ b/docs/old/telemetry-events.md@@ -291,6 +291,14 @@ more easily than it charts a nested object. They count **configured** bridges,whether or not each is currently connected — which is up is process state, and`bridge_connected` / `bridge_disconnected` are how that is reported.+**What counts as a message.** Every durable event is a row in the message log:+arrivals, tool- and LLM-call reports and task transitions sit beside the+conversation. The message counts, the turn counts and every "interacted" figure+above (`user_active_*`, `room_active_*`, `agent_active_7d`) read only what a+participant *said*: chat messages, and commands a person typed on a platform.+The automatic notice Switch posts under an agent's name when it cannot take a+request is excluded as well — the agent did not say it.+**Turns rather than senders.** A turn is one message classified by who sent themessage *before* it in the same room. That is the only way to tell an agentanswering a person from two agents talking among themselves: a sender-only count@@ -322,7 +330,7 @@ deployments installed after this ships — see| Event | Emitted when | Extra properties ||---|---|---|| `deployment_installed` | the deployment id is generated on an empty database | — |-| `first_connector_added` | any bridge first reaches connected | `bridge_platform` |+| `first_connector_added` | the first bridge a **person** added reaches connected | `bridge_platform` || `first_room_created` | the first **user-created** room is created | `channel_type`, `bridge_platform` || `first_room_active` | that room sees its first interaction | `bridge_platform`, `seconds_since_room_created` || `first_agent_registered` | the first agent registers | `known_agent_type` |@@ -351,9 +359,26 @@ telemetry is switched off does not emit it later as though it had just happened.| `bridge_platform` | platform || `seconds_since_install` | number || `seconds_since_configured` | number — configuration saved to first connect |-| `is_first_connector` | boolean |+| `is_preconfigured` | boolean — registered by the deployment's setup step, not a person |+| `is_first_connector` | boolean — the first connector a person added || `failed_attempts_before_success` | number |+**Preconfigured connectors.** The standalone stack, the Helm chart and every+Console-managed local server run a setup step that registers the bundled+Mattermost seconds after install. That connector reports `is_preconfigured:+true`, is never `is_first_connector`, and never claims `first_connector_added`+— so that milestone is the first connector a person added, not the deployment+booting. Filter `connector_added` on `is_preconfigured = false` to measure+onboarding. A bundled connector registered before the flag existed is marked+on the setup step's next run; if it first connects before that, its one+`connector_added` reports `false`.++**`seconds_since_configured` is not setup time for an old connector.** The+event fires on the first connect *seen with telemetry on*. A connector that+already existed when telemetry was switched on reports its whole age on its+first connect afterwards. Deployments that predate telemetry send `-1` in+`seconds_since_install`, so filtering to `>= 0` drops most of them.+`seconds_since_configured` and `failed_attempts_before_success` are what answer"is one platform too hard". Elapsed time from install mostly measures whensomebody got round to it; time from *configuring* a bridge to it actually@@ -441,11 +466,29 @@ that as `false` would misfile a lookup failure as a failed setup.| `registration_path` | `bootstrap` \| `personal_key` \| `gateway` \| `other` || `has_parent` | boolean — a subagent rather than a top-level agent |-**`agent_session_started`** — `known_agent_type`. Deliberately nothing about-*how* the session was started: the server sees an authenticated connection-whether a person launched it or Switch Console spawned it, and a property that-takes the same value on every emission is a dimension that cannot segment-anything.+**`agent_session_started`** — `known_agent_type`. An agent *coming online*: its+first live connection, not a session a person began. Sessions share their+agent's one connection, held by Switch Console or a remote host's sidecar, so+this fires when that connection opens and not again when a session starts on+it. Deliberately nothing about *how*: the server cannot tell, and a property+that takes the same value on every emission cannot segment anything.++**`session_started`** — `start_source` (`user` \| `room` \| `automation` \|+`unknown`), `known_agent_type`. A coding-agent session starting, reported once+by the host that runs it when the session is new — never on a resume. The+launcher stamps `start_source`: `user` is a person starting one in Switch+Console, `room` the agent being addressed in a room, `automation` Console's+local automation API. `unknown` is a launcher that said nothing, reported+rather than dropped so an unstamped launch path is a visible gap. "Sessions a+person started" is `start_source = user`. It is the launcher's claim, not proof+a person clicked, and hosts older than this report nothing.++Guarded against a caller inventing sessions: the id must be a UUID (every+launcher mints one), and an agent reporting more than 120 starts in an hour is+not counted until the rate drops, with a warning logged. The claim that makes a+retried report count once is a row in `telemetry_milestones`, pruned after 7+days by the daily snapshot pass; a report retried later than that, whose first+attempt did arrive, counts twice.**`agent_session_ended`** — `duration_seconds` (number), `reason` (`normal` \|`heartbeat_lapsed` \| `replaced` \| `room_claimed` \| `error`). No runtime: the@@ -688,6 +731,9 @@ Two things to set up first, or a third of the list cannot fire at all:- `agent_session_ended` — kill an agent and wait for the heartbeat sweep(a few seconds). Reported through a listener on the registry, so every paththat closes a connection reports, not just the sweep.+- `session_started` — `POST /agent-sessions/{id}/started` from a session host+ (`bridges/agent/api/activity_routes.py`), with a UUID id. A repeat for the+ same agent and session emits nothing, across restarts, for 7 days.**Connectors** — `bridges/collaboration/lifecycle_service.py`@@ -695,7 +741,8 @@ Two things to set up first, or a third of the list cannot fire at all:`outcome: failure` when it cannot; try bad credentials.- `connector_added` — the *first* successful connect for that bridge, ever.Restarting a working bridge correctly emits nothing.-- `first_connector_added` — the first connector on the deployment.+- `first_connector_added` — the first connector a person added on the+ deployment. The bundled Mattermost the setup step registers never claims it.- `bridge_disconnected` — stopping a bridge (`reason: shutdown`), restartingone (`restart`), or a live bridge crashing.- `connector_removed` — `DELETE /gateway/collaborations/{id}`. Check@@ -744,7 +791,8 @@ reason.`package_detached_from_room` — the inverse of the attach events, so aresource tried and dropped is distinguishable from one never used.- `connector_configured` — the bridge row being written, which is not the same- as it connecting. Many of these and few `bridge_connected` is a deployment+ as it connecting. `is_preconfigured` separates the setup step's own+ connector from one a person added. Many of these and few `bridge_connected` is a deploymentwhose setup is failing, and only the pair shows it.- `server_connector_registered` / `server_connector_removed`.