Skip to content

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

fix(telemetry): dashboard accuracy — session events, message counts, preconfigured connectors, session_started (#558)

Christian McDermott0cb6d99f806a
diff --git a/console/AGENTS.md b/console/AGENTS.md
index 52fcbfb2d..4fc5dcc2f 100644
--- a/console/AGENTS.md
+++ b/console/AGENTS.md
@@ -483,9 +483,12 @@ pnpm run lint
distribution. Note also that `satisfies { [K in Name]: readonly (keyof T[K])[] }`
constrains what an array *may* contain, never what it *must* — that is why
`_everyPropertyIsAllowListed` is a separate check.
-- **The sidecar sends nothing.** It runs headless on a user's VM with no consent prompt
- and no access to this setting, so sessions it starts are not counted. Do not "fix" that
- by having it report; the gate is not reachable from there.
+- **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 the
write 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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', asy
expect(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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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, or
diff --git a/console/packages/agent-providers/src/host/control.test.ts b/console/packages/agent-providers/src/host/control.test.ts
index 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.ts
index 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.ts
index 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', a
supervision.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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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, or
diff --git a/console/packages/agent-providers/src/host/shared-host.test.ts b/console/packages/agent-providers/src/host/shared-host.test.ts
index 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 applie
expect(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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.py
index 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 platform
shows 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 datetime
from typing import Annotated, Any, Literal
+from uuid import UUID
from fastapi import APIRouter, Depends
from pydantic import BaseModel, ConfigDict, Field
@@ -14,7 +16,11 @@ from pydantic.alias_generators import to_camel
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from 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, ApprovalRequest
from 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: Factory
diff --git a/core/switch_core/bridges/agent/api/handlers.py b/core/switch_core/bridges/agent/api/handlers.py
index 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.py
index 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 RoomStore
from switch_core.db.stores.task_store import TaskStore
from switch_core.room_service import RoomService
from 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.py
index 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.py
index 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._preconfigured
emit_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),
+ )
return
elapsed_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.py
index 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 Mapping
from enum import StrEnum
from 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 the
diff --git a/core/switch_core/clients/agent_client.py b/core/switch_core/clients/agent_client.py
index 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 a
diff --git a/core/switch_core/db/models.py b/core/switch_core/db/models.py
index 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.py
index 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.py
index 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_lifecycle
diff --git a/core/switch_core/gateway/schemas.py b/core/switch_core/gateway/schemas.py
index 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: str
agent_greetings_enabled: bool
is_default: bool
+ # Registered by the deployment's own setup step rather than by a person.
+ # See `BridgeCreateRequest.preconfigured`.
+ preconfigured: bool
room_count: int
created_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 = None
channel_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 = False
class 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.py
new file mode 100644
index 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.py
index 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.py
index 3cd39c97f..d4b7c5cf2 100644
--- a/core/switch_core/telemetry/deployment.py
+++ b/core/switch_core/telemetry/deployment.py
@@ -16,7 +16,7 @@ import logging
from datetime import UTC, datetime
from typing import Literal
-from sqlalchemy import select
+from sqlalchemy import delete, select
from sqlalchemy.dialects.postgresql import insert as pg_insert
from 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.py
index 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_sessionmaker
from switch_core.db.models import TelemetrySnapshotWatermark
from switch_core.telemetry.deployment import claim_milestone
from switch_core.telemetry.service import TelemetryService
+from switch_core.telemetry.session_start import prune_session_start_claims
from switch_core.telemetry.snapshot import (
as_utc,
collect_usage,
@@ -84,8 +85,22 @@ class SnapshotReporter:
return False
await 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.py
new file mode 100644
index 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.py
index 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_sessionmaker
from sqlalchemy.orm import aliased
+from switch_core.clients.admin_messages import AUTO_REPLY_FLAG
from 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, and
it 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 which
diff --git a/core/tests/deploy/test_setup_register_bridge.py b/core/tests/deploy/test_setup_register_bridge.py
index 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.py
index 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 asyncio
from types import SimpleNamespace
from typing import Any
@@ -14,15 +15,19 @@ import pytest
from fastapi import HTTPException
from starlette.responses import StreamingResponse
+from switch_core.bridges.agent.api import session_reporter
from switch_core.bridges.agent.api.handlers import _resolve_start_cursor, poll_events
from switch_core.bridges.agent.api.session_reporter import SessionReporter
from 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 TelemetryRecord
AGENT_ID = "agent-1"
@@ -346,3 +351,122 @@ class TestDeclaringARoomAtOpenTakesOver:
assert claimant is not None
assert 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.py
index 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 pytest
from fastapi import HTTPException
from switch_core.bridges.agent.api.handlers import poll_events
+from switch_core.bridges.agent.api.session_reporter import SessionReporter
from 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.py
index 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.py
index 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 False
assert install.bridge_id is not None
async 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.py
index 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._preconfigured
diff --git a/core/tests/switch_core/bridges/collaboration/test_teams_zero_config.py b/core/tests/switch_core/bridges/collaboration/test_teams_zero_config.py
index 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() -> Non
display_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() -> No
display_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.py
index 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 annotations
from contextlib import asynccontextmanager
from types import SimpleNamespace
+from switch_core.clients.admin_messages import AUTO_REPLY_FLAG
from 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 AgentClient
from 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.py
new file mode 100644
index 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 False
diff --git a/core/tests/switch_core/session_activity/test_session_started_route.py b/core/tests/switch_core/session_activity/test_session_started_route.py
new file mode 100644
index 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.py
index 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 annotations
import uuid
+from datetime import datetime
from typing import Any
from 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.py
index 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 annotations
from typing import Any
from 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_telemetry
from switch_core.bridges.agent.protocol.event_buffer import EventBuffer
from switch_core.telemetry.service import TelemetryService
from 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 telemetry
diff --git a/core/tests/switch_core/telemetry/test_preconfigured_connectors.py b/core/tests/switch_core/telemetry/test_preconfigured_connectors.py
new file mode 100644
index 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.py
new file mode 100644
index 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 False
diff --git a/core/tests/switch_core/telemetry/test_snapshot.py b/core/tests/switch_core/telemetry/test_snapshot.py
index 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, timedelta
from sqlalchemy import delete
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+from switch_core.clients.admin_messages import AUTO_REPLY_FLAG
+from switch_core.clients.client_base import ClientBase
from 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_TYPE
from 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.py
index 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.md
index 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 the
message *before* it in the same room. That is the only way to tell an agent
answering 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 when
somebody 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 path
that 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`), restarting
one (`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 a
resource 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 deployment
whose setup is failing, and only the pair shows it.
- `server_connector_registered` / `server_connector_removed`.