Skip to content

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

E2E coverage gate over agent operations and gateway routes

Petr Bauch4c26a5c8c9b9
diff --git a/.github/workflows/pr-ci.yml b/.github/workflows/pr-ci.yml
index b514582c1..cf38cf5ab 100644
--- a/.github/workflows/pr-ci.yml
+++ b/.github/workflows/pr-ci.yml
@@ -96,6 +96,10 @@ jobs:
- 'scripts/check_migration_heads_for_open_prs.py'
- 'scripts/pin_chart_images.py'
- 'scripts/prune_dev_packages.py'
+ # The end-to-end coverage gate's snapshot of the server's surface,
+ # checked against the server below.
+ - 'scripts/e2e_surface.py'
+ - 'console/tooling-e2e/surface/**'
console:
- *shared
- 'console/**'
@@ -172,6 +176,13 @@ jobs:
- name: mypy
run: uv run --project core mypy --config-file core/pyproject.toml core/switch_core/
+ # The coverage gate in console/tooling-e2e reads this snapshot rather
+ # than the server, so it has to be the server's: a route or operation
+ # added without regenerating it fails here, and the regenerated snapshot
+ # then fails the gate until a scenario or an exemption accounts for it.
+ - name: E2E surface snapshot is current
+ run: uv run --project core python scripts/e2e_surface.py --check
+
# Store tests boot real Postgres via testcontainers; ubuntu-latest ships
# Docker so the containers come up without extra setup. The slow
# integration suite (Postgres + Tuwunel) is excluded from the default run
diff --git a/console/tooling-e2e/README.md b/console/tooling-e2e/README.md
index c090e3098..47ed0fcce 100644
--- a/console/tooling-e2e/README.md
+++ b/console/tooling-e2e/README.md
@@ -68,6 +68,9 @@ Typecheck: `pnpm typecheck`.
| `scripts/ephemeral-stack.sh` | The throwaway-stack runner behind `just e2e-fast` and `just e2e-provider` |
| `scripts/scan-artifacts.sh` | Fails if a run's output holds one of the secrets the run used |
| `src/ci-summary.ts` | The CI run summary, read from the JUnit report |
+| `src/gate/` | The coverage gate |
+| `surface/server-surface.json` | The server's operations and gateway routes, generated by `just e2e-surface` |
+| `surface/exemptions.json` | What no scenario covers, each entry with its reason, and the backlog |
## Scenarios and their headers
@@ -211,6 +214,48 @@ Two things differ from a Console session:
The controller's log goes to `build/e2e/ephemeral/controller.log`.
+## Coverage gate
+
+The coverage gate catches functionality that ships without an end-to-end
+scenario. Every agent operation and every gateway route the server has must be
+covered by a scenario header (`covers`) or listed in `surface/exemptions.json`.
+The gate is an ordinary unit test (`src/gate/coverage.test.ts`), so it runs
+on every PR with no server.
+
+- **Where the surface comes from.** The gate reads a committed snapshot of the
+ server: `surface/server-surface.json`, written by `just e2e-surface`
+ (`scripts/e2e_surface.py`). It lists:
+ - every declared agent operation, gated groups included. One definition
+ serves both MCP and the HTTP front door, so this is the agent surface
+ whichever door an agent uses;
+ - every gateway route, with every feature flag on, and what it authenticates
+ with: `session`, `operator-token` (the hosted controller's machine routes)
+ or `none`.
+
+ The backend CI job runs the script with `--check`, so a route added without
+ regenerating fails there. Once the snapshot is regenerated, the gate fails
+ until the new route is accounted for.
+- **What counts as covered.** An entry in some scenario's `covers`. Operation
+ names and `/gateway/…` routes are checked against the snapshot, so a renamed
+ route fails as a stale claim. Agent-bridge routes (`/agents/…`) are not
+ snapshotted yet and pass unchecked.
+- **`exemptions.json`** has three lists:
+ - `exempt`: deliberately not covered end to end, each with its reason (it
+ needs a real third-party sign-in, say).
+ - `unauthenticated`: every route that takes no credential, each with the
+ reason that is right. A route that loses its session check shows up as
+ `none` and fails until someone says why that is fine.
+ - `backlog`: what no scenario covered when the gate landed. It only shrinks.
+ When a scenario starts covering an entry, the gate fails until the entry is
+ removed. Never add to it: a new route needs a scenario or an `exempt` entry
+ with its reason.
+- **A check derived from the snapshot.** The fast lane checks that every
+ `session` route the deployment mounts answers 401 to a request carrying no
+ credential. It reads which routes are mounted from the deployment's own
+ OpenAPI document, so routes behind flags that are off are left out and
+ counted. This check counts nothing towards coverage, but it applies to every
+ new route automatically.
+
## In CI
`.github/workflows/e2e.yml` defines a run: one lane against one environment
diff --git a/console/tooling-e2e/src/clients/switch-client.ts b/console/tooling-e2e/src/clients/switch-client.ts
index 6cf445f99..5b9751234 100644
--- a/console/tooling-e2e/src/clients/switch-client.ts
+++ b/console/tooling-e2e/src/clients/switch-client.ts
@@ -190,6 +190,42 @@ export class SwitchClient {
return { parsed: text === '' ? undefined : JSON.parse(text), response };
}
+ /**
+ * The status a request with no credential at all gets: no cookie, no bearer
+ * key, no body. For the check that every route which takes a session refuses
+ * a request without one.
+ */
+ async statusWithoutCredentials(method: string, path: string): Promise<number> {
+ assertAllowed(this.environment, method, path);
+ const response = await fetch(`${this.apiUrl}${path}`, {
+ method,
+ headers: { Accept: 'application/json' },
+ redirect: 'manual',
+ signal: AbortSignal.timeout(30_000),
+ });
+ await response.body?.cancel();
+ return response.status;
+ }
+
+ /**
+ * The gateway routes this deployment mounts, as `METHOD /gateway/path`, from
+ * its own OpenAPI document (served without a session). Routes behind a
+ * feature flag the deployment has off are not in it.
+ */
+ async mountedGatewayRoutes(): Promise<Set<string>> {
+ const document = await this.request<{ paths: Record<string, Record<string, unknown>> }>(
+ 'GET',
+ '/gateway/openapi.json'
+ );
+ const routes = new Set<string>();
+ for (const [path, operations] of Object.entries(document.paths)) {
+ for (const method of Object.keys(operations)) {
+ routes.add(`${method.toUpperCase()} /gateway${path}`);
+ }
+ }
+ return routes;
+ }
+
/** `GET /health` — the reachability probe the suite skips on. */
async health(): Promise<void> {
const body = await this.request<{ status?: string }>('GET', '/health', {
diff --git a/console/tooling-e2e/src/fast/fast.e2e.test.ts b/console/tooling-e2e/src/fast/fast.e2e.test.ts
index ca7224875..7d4daea7a 100644
--- a/console/tooling-e2e/src/fast/fast.e2e.test.ts
+++ b/console/tooling-e2e/src/fast/fast.e2e.test.ts
@@ -3,8 +3,10 @@ import { describeEnv } from '../core/env.ts';
import { RunContext } from '../core/run.ts';
import { admit, assertValidHeaders } from '../core/scenario.ts';
import { resolveLane, type LaneResolution } from '../core/suite.ts';
+import { readSurface } from '../gate/gate.ts';
import { Fixtures } from '../fixtures/fixtures.ts';
import { FAST_SCENARIOS } from './index.ts';
+import { probeSessionRoutes } from './session-required.ts';
/**
* The fast lane: provider-free scenarios against a Switch server, one fresh
@@ -59,3 +61,19 @@ describe('fast lane', () => {
});
}
});
+
+describe('fast lane, derived checks', () => {
+ // Sends writes (without a credential), so it stays off prod like every
+ // scenario that writes.
+ it('every gateway route that takes a session refuses a request without one', async (context) => {
+ if (!lane.target) return context.skip(lane.skip);
+ if (lane.target.env.environment === 'prod') return context.skip('sends writes; not on prod');
+ const probe = await probeSessionRoutes(lane.target.switchClient, readSurface());
+ console.log(
+ `[session-required] probed ${probe.probed} session routes; ` +
+ `${probe.notMounted} more are not mounted here (feature flags off)`
+ );
+ expect(probe.probed, 'no session route was probed').toBeGreaterThan(0);
+ expect(probe.wrong, `answered without a session:\n ${probe.wrong.join('\n ')}\n`).toEqual([]);
+ }, 120_000);
+});
diff --git a/console/tooling-e2e/src/fast/session-required.ts b/console/tooling-e2e/src/fast/session-required.ts
new file mode 100644
index 000000000..0c798c17c
--- /dev/null
+++ b/console/tooling-e2e/src/fast/session-required.ts
@@ -0,0 +1,53 @@
+import type { SwitchClient } from '../clients/switch-client.ts';
+import type { ServerSurface } from '../gate/gate.ts';
+
+/**
+ * A check derived from the surface snapshot rather than written per route:
+ * every gateway route that takes a signed-in session answers 401 to a request
+ * that carries none.
+ *
+ * It covers nothing in the coverage gate's sense — a 401 says nothing about
+ * what the route does — but it is free for every route the server adds, and
+ * catches a session check that a refactor dropped, which the snapshot would
+ * only show as a route moving to `none` in a diff.
+ *
+ * Only routes the deployment mounts are probed, read from its own OpenAPI
+ * document: a route behind a feature flag it has off answers 404 for that
+ * reason alone. Path parameters get a well-formed id that names nothing: the
+ * session check runs before the route ever looks the id up.
+ */
+
+const PLACEHOLDER_ID = '00000000-0000-4000-8000-000000000000';
+
+export function probePath(route: string): { method: string; path: string } {
+ const [method, template] = route.split(' ', 2) as [string, string];
+ return { method, path: template.replace(/\{[^}]+\}/g, PLACEHOLDER_ID) };
+}
+
+export interface SessionProbe {
+ probed: number;
+ /** Session routes in the snapshot this deployment does not mount. */
+ notMounted: number;
+ /** Each probed route that did not answer 401, with what it answered. */
+ wrong: string[];
+}
+
+export async function probeSessionRoutes(
+ switchClient: SwitchClient,
+ surface: ServerSurface
+): Promise<SessionProbe> {
+ const mounted = await switchClient.mountedGatewayRoutes();
+ const result: SessionProbe = { probed: 0, notMounted: 0, wrong: [] };
+ for (const { route, auth } of surface.gatewayRoutes) {
+ if (auth !== 'session') continue;
+ if (!mounted.has(route)) {
+ result.notMounted += 1;
+ continue;
+ }
+ const { method, path } = probePath(route);
+ const status = await switchClient.statusWithoutCredentials(method, path);
+ result.probed += 1;
+ if (status !== 401) result.wrong.push(`${route} -> ${status}`);
+ }
+ return result;
+}
diff --git a/console/tooling-e2e/src/gate/coverage.test.ts b/console/tooling-e2e/src/gate/coverage.test.ts
new file mode 100644
index 000000000..109a4964c
--- /dev/null
+++ b/console/tooling-e2e/src/gate/coverage.test.ts
@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest';
+import type { ScenarioHeader } from '../core/scenario.ts';
+import { FAST_SCENARIOS } from '../fast/index.ts';
+import { SCENARIOS as PROVIDER_SCENARIOS } from '../provider/scenarios.ts';
+import {
+ coverageProblems,
+ readExemptions,
+ readSurface,
+ type Exemptions,
+ type ServerSurface,
+} from './gate.ts';
+
+const HEADERS = [...FAST_SCENARIOS, ...PROVIDER_SCENARIOS].map((scenario) => scenario.header);
+
+describe('coverage gate', () => {
+ it('accounts for every operation and gateway route the server has', () => {
+ const problems = coverageProblems(readSurface(), readExemptions(), HEADERS);
+ expect(problems, `\n ${problems.join('\n ')}\n`).toEqual([]);
+ });
+});
+
+const SURFACE: ServerSurface = {
+ operations: ['list_rooms', 'post_message'],
+ gatewayRoutes: [
+ { route: 'POST /gateway/rooms', auth: 'session' },
+ { route: 'POST /gateway/auth/login', auth: 'none' },
+ ],
+};
+
+function header(id: string, covers: string[]): ScenarioHeader {
+ return { id, covers, needsProvider: false, environments: ['ephemeral'], owner: 'platform', requires: [] };
+}
+
+function exemptions(overrides: Partial<Exemptions>): Exemptions {
+ return {
+ exempt: { 'POST /gateway/auth/login': 'How a session is obtained.' },
+ unauthenticated: { 'POST /gateway/auth/login': 'How a session is obtained.' },
+ backlog: ['post_message'],
+ ...overrides,
+ };
+}
+
+describe('coverage gate rules', () => {
+ const covering = [header('rooms', ['list_rooms', 'POST /gateway/rooms', 'GET /agents/{agent_id}/ops'])];
+
+ it('passes when everything is covered, exempt or in the backlog', () => {
+ expect(coverageProblems(SURFACE, exemptions({}), covering)).toEqual([]);
+ });
+
+ it('fails on a new operation or route nothing accounts for', () => {
+ const grown: ServerSurface = {
+ operations: [...SURFACE.operations, 'archive_room'],
+ gatewayRoutes: [...SURFACE.gatewayRoutes, { route: 'DELETE /gateway/rooms/{room_id}', auth: 'session' }],
+ };
+ const problems = coverageProblems(grown, exemptions({}), covering);
+ expect(problems).toHaveLength(2);
+ expect(problems.join('\n')).toContain("'archive_room' is covered by no scenario");
+ expect(problems.join('\n')).toContain("'DELETE /gateway/rooms/{room_id}' is covered by no scenario");
+ });
+
+ it('fails on a backlog entry a scenario now covers, and on stale entries', () => {
+ const problems = coverageProblems(
+ SURFACE,
+ exemptions({ backlog: ['post_message', 'list_rooms', 'gone_operation'] }),
+ covering
+ );
+ expect(problems.join('\n')).toContain("backlog lists 'list_rooms', which rooms now covers");
+ expect(problems.join('\n')).toContain("backlog lists 'gone_operation', which the server does not have");
+ });
+
+ it('fails on a header covering what the server does not have, ignoring the agent bridge', () => {
+ const problems = coverageProblems(SURFACE, exemptions({}), [
+ ...covering,
+ header('stale', ['list_room', 'GET /gateway/nowhere', 'POST /agents/register-known']),
+ ]);
+ expect(problems).toHaveLength(2);
+ expect(problems.join('\n')).toContain("stale covers 'list_room'");
+ expect(problems.join('\n')).toContain("stale covers 'GET /gateway/nowhere'");
+ });
+
+ it('wants a reason for every exemption, and for every route that takes no credential', () => {
+ const problems = coverageProblems(
+ SURFACE,
+ exemptions({ exempt: { 'POST /gateway/auth/login': ' ' }, unauthenticated: {} }),
+ covering
+ );
+ expect(problems.join('\n')).toContain("exempt lists 'POST /gateway/auth/login' without a reason");
+ expect(problems.join('\n')).toContain("'POST /gateway/auth/login' takes no credential");
+ });
+
+ it('fails when a route listed as unauthenticated has gained a credential', () => {
+ const problems = coverageProblems(
+ SURFACE,
+ exemptions({
+ unauthenticated: {
+ 'POST /gateway/auth/login': 'How a session is obtained.',
+ 'POST /gateway/rooms': 'Was public once.',
+ },
+ }),
+ covering
+ );
+ expect(problems).toEqual([
+ "unauthenticated lists 'POST /gateway/rooms', which is not a route taking no credential",
+ ]);
+ });
+});
diff --git a/console/tooling-e2e/src/gate/gate.ts b/console/tooling-e2e/src/gate/gate.ts
new file mode 100644
index 000000000..9d5162be5
--- /dev/null
+++ b/console/tooling-e2e/src/gate/gate.ts
@@ -0,0 +1,137 @@
+/**
+ * The coverage gate: every agent operation and gateway route the server has is
+ * accounted for, by a scenario that covers it or an exemption that says why not.
+ *
+ * It reads the server's surface from a committed snapshot
+ * (`surface/server-surface.json`, written by `scripts/e2e_surface.py`, kept
+ * current by that script's `--check` in CI), so it needs no server and runs as
+ * an ordinary unit test on every PR. A new operation or route therefore fails
+ * the build until a scenario covers it or an exemption names it, with a reason.
+ *
+ * `surface/exemptions.json` holds three lists:
+ *
+ * - `exempt`: deliberately not covered end to end, each with its reason;
+ * - `unauthenticated`: routes that take no credential at all, each with the
+ * reason that is right. A route that loses its session check fails here
+ * until someone says why that is fine;
+ * - `backlog`: what was uncovered when the gate landed. It only shrinks: an
+ * entry a scenario now covers fails until it is removed.
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { ScenarioHeader } from '../core/scenario.ts';
+
+export type RouteAuth = 'session' | 'operator-token' | 'none';
+
+export interface ServerSurface {
+ operations: string[];
+ gatewayRoutes: { route: string; auth: RouteAuth }[];
+}
+
+export interface Exemptions {
+ exempt: Record<string, string>;
+ unauthenticated: Record<string, string>;
+ backlog: string[];
+}
+
+const SURFACE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'surface');
+
+export function readSurface(): ServerSurface {
+ return JSON.parse(
+ readFileSync(path.join(SURFACE_DIR, 'server-surface.json'), 'utf8')
+ ) as ServerSurface;
+}
+
+export function readExemptions(): Exemptions {
+ const raw = JSON.parse(readFileSync(path.join(SURFACE_DIR, 'exemptions.json'), 'utf8')) as Record<
+ string,
+ unknown
+ >;
+ return {
+ exempt: raw.exempt as Record<string, string>,
+ unauthenticated: raw.unauthenticated as Record<string, string>,
+ backlog: raw.backlog as string[],
+ };
+}
+
+/** What the gate is about: operations, and routes under `/gateway`. */
+function inScope(entry: string): boolean {
+ return !entry.includes(' ') || entry.includes(' /gateway/');
+}
+
+/** Every problem, so one pass fixes them all. Empty when the gate passes. */
+export function coverageProblems(
+ surface: ServerSurface,
+ exemptions: Exemptions,
+ headers: readonly ScenarioHeader[]
+): string[] {
+ const problems: string[] = [];
+ const known = new Set([...surface.operations, ...surface.gatewayRoutes.map((r) => r.route)]);
+
+ const coveredBy = new Map<string, string[]>();
+ for (const header of headers) {
+ for (const entry of header.covers) {
+ if (!inScope(entry)) continue;
+ if (!known.has(entry)) {
+ problems.push(
+ `${header.id} covers '${entry}', which the server does not have ` +
+ `(renamed or removed? the snapshot is surface/server-surface.json)`
+ );
+ continue;
+ }
+ coveredBy.set(entry, [...(coveredBy.get(entry) ?? []), header.id]);
+ }
+ }
+
+ const backlog = new Set(exemptions.backlog);
+ for (const entry of exemptions.backlog) {
+ if (!known.has(entry)) problems.push(`backlog lists '${entry}', which the server does not have`);
+ else if (coveredBy.has(entry)) {
+ problems.push(
+ `backlog lists '${entry}', which ${coveredBy.get(entry)!.join(', ')} now covers — remove it`
+ );
+ }
+ }
+ if (backlog.size !== exemptions.backlog.length) problems.push('backlog lists an entry twice');
+
+ for (const [entry, reason] of Object.entries(exemptions.exempt)) {
+ if (!known.has(entry)) problems.push(`exempt lists '${entry}', which the server does not have`);
+ else if (coveredBy.has(entry)) {
+ problems.push(
+ `exempt lists '${entry}', which ${coveredBy.get(entry)!.join(', ')} covers — remove it`
+ );
+ }
+ if (reason.trim() === '') problems.push(`exempt lists '${entry}' without a reason`);
+ if (backlog.has(entry)) problems.push(`'${entry}' is both exempt and in the backlog`);
+ }
+
+ for (const entry of known) {
+ if (!coveredBy.has(entry) && !(entry in exemptions.exempt) && !backlog.has(entry)) {
+ problems.push(
+ `'${entry}' is covered by no scenario: add one whose header covers it, or ` +
+ `exempt it in surface/exemptions.json with the reason`
+ );
+ }
+ }
+
+ const unauthenticated = new Set(
+ surface.gatewayRoutes.filter((r) => r.auth === 'none').map((r) => r.route)
+ );
+ for (const route of unauthenticated) {
+ if (!(route in exemptions.unauthenticated)) {
+ problems.push(
+ `'${route}' takes no credential: if that is right, list it under ` +
+ `unauthenticated in surface/exemptions.json with the reason`
+ );
+ }
+ }
+ for (const [route, reason] of Object.entries(exemptions.unauthenticated)) {
+ if (!unauthenticated.has(route)) {
+ problems.push(`unauthenticated lists '${route}', which is not a route taking no credential`);
+ }
+ if (reason.trim() === '') problems.push(`unauthenticated lists '${route}' without a reason`);
+ }
+
+ return problems;
+}
diff --git a/console/tooling-e2e/surface/exemptions.json b/console/tooling-e2e/surface/exemptions.json
new file mode 100644
index 000000000..396af9ff6
--- /dev/null
+++ b/console/tooling-e2e/surface/exemptions.json
@@ -0,0 +1,323 @@
+{
+ "_about": "Read by src/gate/gate.ts; see the README, \"Coverage gate\". exempt and unauthenticated need a reason per entry. backlog is what no scenario covered when the gate landed: it only shrinks, and the gate fails on an entry a scenario now covers.",
+ "exempt": {
+ "GET /gateway/docs": "FastAPI's generated API documentation; no behaviour of Switch's own to cover.",
+ "GET /gateway/docs/oauth2-redirect": "FastAPI's generated API documentation; no behaviour of Switch's own to cover.",
+ "GET /gateway/redoc": "FastAPI's generated API documentation; no behaviour of Switch's own to cover.",
+ "GET /gateway/openapi.json": "FastAPI's generated API documentation; no behaviour of Switch's own to cover.",
+ "GET /gateway/auth/oidc/login": "Needs a live OIDC identity provider; the harness signs in with a password.",
+ "GET /gateway/auth/oidc/callback": "Needs a live OIDC identity provider; the harness signs in with a password.",
+ "GET /gateway/provider-connections/github/authorize": "Needs a registered GitHub App and a browser round trip through github.com.",
+ "GET /gateway/provider-connections/github/callback": "Needs a registered GitHub App and a browser round trip through github.com.",
+ "POST /gateway/provider-connections/github/callback": "Needs a registered GitHub App and a browser round trip through github.com.",
+ "GET /gateway/service-connections/{service}/flows/authorize": "Needs the third-party service's own sign-in page in a browser.",
+ "GET /gateway/service-connections/{service}/flows/callback": "Needs the third-party service's own sign-in page in a browser.",
+ "POST /gateway/service-connections/{service}/flows/callback": "Needs the third-party service's own sign-in page in a browser.",
+ "GET /gateway/hosted-controller/machines": "Needs a hosted controller configured (HOSTED_CONTROLLER_CONFIG_PATH), which no stack the harness builds has.",
+ "POST /gateway/hosted-controller/machines/{machine_id}/prepare": "Needs a hosted controller configured (HOSTED_CONTROLLER_CONFIG_PATH), which no stack the harness builds has.",
+ "POST /gateway/hosted-controller/machines/{machine_id}/observation": "Needs a hosted controller configured (HOSTED_CONTROLLER_CONFIG_PATH), which no stack the harness builds has."
+ },
+ "unauthenticated": {
+ "GET /gateway/docs": "FastAPI's generated docs, served without a session. They publish the gateway's whole route list and schemas to anyone who can reach it.",
+ "GET /gateway/docs/oauth2-redirect": "FastAPI's generated docs, served without a session. They publish the gateway's whole route list and schemas to anyone who can reach it.",
+ "GET /gateway/redoc": "FastAPI's generated docs, served without a session. They publish the gateway's whole route list and schemas to anyone who can reach it.",
+ "GET /gateway/openapi.json": "FastAPI's generated docs, served without a session. They publish the gateway's whole route list and schemas to anyone who can reach it.",
+ "POST /gateway/auth/login": "How a session is obtained.",
+ "POST /gateway/auth/signup": "How an account, and its first session, is created.",
+ "POST /gateway/auth/logout": "Only clears the session cookie; there is nothing behind it to protect.",
+ "GET /gateway/auth/config": "Read by the login page before any session exists, to choose which sign-in methods to offer.",
+ "GET /gateway/auth/oidc/login": "The OIDC sign-in round trip, before any session exists.",
+ "GET /gateway/auth/oidc/callback": "The OIDC sign-in round trip, before any session exists.",
+ "GET /gateway/provider-connections/github/authorize": "The GitHub App's redirect round trip: the sign-in flow is identified by its state parameter, not a session.",
+ "GET /gateway/provider-connections/github/callback": "The GitHub App's redirect round trip: the sign-in flow is identified by its state parameter, not a session.",
+ "POST /gateway/provider-connections/github/callback": "The GitHub App's redirect round trip: the sign-in flow is identified by its state parameter, not a session.",
+ "GET /gateway/service-connections/{service}/flows/authorize": "The third-party sign-in round trip: the flow is identified by its state, not a session.",
+ "GET /gateway/service-connections/{service}/flows/callback": "The third-party sign-in round trip: the flow is identified by its state, not a session.",
+ "POST /gateway/service-connections/{service}/flows/callback": "The third-party sign-in round trip: the flow is identified by its state, not a session.",
+ "GET /gateway/agents/known-types": "The catalogue of agent types this server can register and their option schemas; no tenant data. Public since the initial import, and nothing records whether that is deliberate."
+ },
+ "backlog": [
+ "accept_task",
+ "add_users_to_room",
+ "archive_room",
+ "assume_role",
+ "attach_reference_to_room",
+ "cancel_task",
+ "create_agent",
+ "create_reference",
+ "create_room",
+ "create_room_document",
+ "create_room_from_yaml",
+ "create_room_group",
+ "define_role",
+ "delegate_task",
+ "delete_role",
+ "delete_room_document",
+ "delete_template",
+ "edit_role",
+ "finalise_task",
+ "get_advanced_config",
+ "get_agent_detail",
+ "get_role_detail",
+ "get_room_detail",
+ "get_room_group_detail",
+ "get_template",
+ "get_template_guide",
+ "invite_agent_to_room",
+ "link_rooms",
+ "list_agents",
+ "list_all_references",
+ "list_all_rooms",
+ "list_bridges",
+ "list_linked_rooms",
+ "list_machines",
+ "list_managed_agents",
+ "list_participants",
+ "list_reference_types",
+ "list_references",
+ "list_roles",
+ "list_room_groups",
+ "list_tasks",
+ "list_templates",
+ "load_internal_documents",
+ "release_role",
+ "run_template",
+ "save_template",
+ "send_targeted_message",
+ "unarchive_room",
+ "unlink_rooms",
+ "update_agent_detail",
+ "update_room",
+ "update_room_document",
+ "update_task",
+ "update_template",
+ "DELETE /gateway/agents/by-name/{agent_name}",
+ "DELETE /gateway/agents/{agent_id}",
+ "DELETE /gateway/agents/{agent_id}/service-grants/{service}",
+ "DELETE /gateway/api-keys/{key_id}",
+ "DELETE /gateway/chats/{room_id}/hidden",
+ "DELETE /gateway/chats/{room_id}/members/{member_user_id}",
+ "DELETE /gateway/collaborations/{bridge_id}",
+ "DELETE /gateway/collaborations/{bridge_id}/identities/{external_user_row_id}",
+ "DELETE /gateway/collaborations/{bridge_id}/teams/{team_id}",
+ "DELETE /gateway/connectors/{connector_id}",
+ "DELETE /gateway/documents/{document_id}",
+ "DELETE /gateway/management/agents/{agent_id}",
+ "DELETE /gateway/management/controllers/{controller_id}",
+ "DELETE /gateway/management/controllers/{controller_id}/provider-logins/{provider}",
+ "DELETE /gateway/messaging-apps/installs/{install_id}",
+ "DELETE /gateway/packages/{package_id}",
+ "DELETE /gateway/packages/{package_id}/documents/{document_id}",
+ "DELETE /gateway/packages/{package_id}/references/{reference_id}",
+ "DELETE /gateway/provider-connections/github",
+ "DELETE /gateway/provider-connections/github/flows/{flow_id}",
+ "DELETE /gateway/references/reference-types/{type}",
+ "DELETE /gateway/references/{reference_id}",
+ "DELETE /gateway/room-groups/{group_id}",
+ "DELETE /gateway/rooms/{room_id}",
+ "DELETE /gateway/rooms/{room_id}/agents/{agent_id}",
+ "DELETE /gateway/rooms/{room_id}/documents/{document_id}",
+ "DELETE /gateway/rooms/{room_id}/linked-rooms/{target_room_id}",
+ "DELETE /gateway/rooms/{room_id}/packages/{package_id}",
+ "DELETE /gateway/rooms/{room_id}/references/{reference_id}",
+ "DELETE /gateway/rooms/{room_id}/roles/{name}",
+ "DELETE /gateway/service-connections/{service}",
+ "DELETE /gateway/service-connections/{service}/flows/{flow_id}",
+ "DELETE /gateway/templates/{template_id}",
+ "DELETE /gateway/tenants/{tenant_id}/budgets/{budget_id}",
+ "DELETE /gateway/tenants/{tenant_id}/invitations/{invitation_id}",
+ "DELETE /gateway/tenants/{tenant_id}/join-domains/{domain}",
+ "DELETE /gateway/tenants/{tenant_id}/members/{user_id}",
+ "DELETE /gateway/trust-settings",
+ "GET /gateway/agent-sessions/approvals",
+ "GET /gateway/agents",
+ "GET /gateway/agents/avatar-settings",
+ "GET /gateway/agents/icon-choices",
+ "GET /gateway/agents/known-types",
+ "GET /gateway/agents/{agent_id}",
+ "GET /gateway/agents/{agent_id}/service-grants",
+ "GET /gateway/api-keys",
+ "GET /gateway/api-keys/{key_id}/reveal",
+ "GET /gateway/auth/config",
+ "GET /gateway/auth/me",
+ "GET /gateway/auth/me/identities",
+ "GET /gateway/auth/session",
+ "GET /gateway/chats",
+ "GET /gateway/chats/activity/events",
+ "GET /gateway/chats/events",
+ "GET /gateway/chats/{room_id}/activity",
+ "GET /gateway/chats/{room_id}/media",
+ "GET /gateway/chats/{room_id}/members",
+ "GET /gateway/chats/{room_id}/messages",
+ "GET /gateway/collaborations",
+ "GET /gateway/collaborations/types",
+ "GET /gateway/collaborations/{bridge_id}/directory",
+ "GET /gateway/collaborations/{bridge_id}/teams",
+ "GET /gateway/collaborations/{bridge_id}/teams-package",
+ "GET /gateway/collaborations/{bridge_id}/users",
+ "GET /gateway/connectors",
+ "GET /gateway/connectors/types",
+ "GET /gateway/connectors/{connector_id}",
+ "GET /gateway/documents",
+ "GET /gateway/documents/{document_id}",
+ "GET /gateway/documents/{document_id}/rooms",
+ "GET /gateway/ecosystem/graph",
+ "GET /gateway/feature-flags",
+ "GET /gateway/hosted-machines",
+ "GET /gateway/hosted-machines/{machine_id}",
+ "GET /gateway/invitations/mine",
+ "GET /gateway/joinable-tenants",
+ "GET /gateway/linked-rooms/graph",
+ "GET /gateway/management/advanced-config",
+ "GET /gateway/management/agents",
+ "GET /gateway/management/agents/{agent_id}",
+ "GET /gateway/management/controllers",
+ "GET /gateway/management/controllers/{controller_id}/provider-logins",
+ "GET /gateway/management/operations",
+ "GET /gateway/management/providers",
+ "GET /gateway/messaging-apps",
+ "GET /gateway/messaging-apps/installs",
+ "GET /gateway/packages",
+ "GET /gateway/packages/{package_id}",
+ "GET /gateway/packages/{package_id}/documents",
+ "GET /gateway/packages/{package_id}/references",
+ "GET /gateway/packages/{package_id}/rooms",
+ "GET /gateway/provider-connections/catalog",
+ "GET /gateway/provider-connections/github",
+ "GET /gateway/provider-connections/github/flows/{flow_id}",
+ "GET /gateway/references",
+ "GET /gateway/references/reference-types",
+ "GET /gateway/references/reference-types/owned",
+ "GET /gateway/references/{reference_id}",
+ "GET /gateway/references/{reference_id}/rooms",
+ "GET /gateway/room-groups",
+ "GET /gateway/rooms",
+ "GET /gateway/rooms/template-schema",
+ "GET /gateway/rooms/{room_id}",
+ "GET /gateway/rooms/{room_id}/documents",
+ "GET /gateway/rooms/{room_id}/documents/{document_id}",
+ "GET /gateway/rooms/{room_id}/linked-rooms",
+ "GET /gateway/rooms/{room_id}/linked-rooms/inbound",
+ "GET /gateway/rooms/{room_id}/packages",
+ "GET /gateway/rooms/{room_id}/references",
+ "GET /gateway/rooms/{room_id}/roles",
+ "GET /gateway/rooms/{room_id}/yaml",
+ "GET /gateway/service-connections",
+ "GET /gateway/service-connections/{service}/flows/{flow_id}",
+ "GET /gateway/template-runs",
+ "GET /gateway/templates",
+ "GET /gateway/templates/{template_id}",
+ "GET /gateway/templates/{template_id}/content",
+ "GET /gateway/tenants",
+ "GET /gateway/tenants/current",
+ "GET /gateway/tenants/{tenant_id}/audit-events",
+ "GET /gateway/tenants/{tenant_id}/budgets",
+ "GET /gateway/tenants/{tenant_id}/invitations",
+ "GET /gateway/tenants/{tenant_id}/join-domains",
+ "GET /gateway/tenants/{tenant_id}/members",
+ "GET /gateway/tenants/{tenant_id}/usage",
+ "GET /gateway/trust-settings",
+ "GET /gateway/users",
+ "GET /gateway/version",
+ "PATCH /gateway/agents/{agent_id}/options",
+ "PATCH /gateway/collaborations/{bridge_id}",
+ "PATCH /gateway/documents/{document_id}",
+ "PATCH /gateway/management/agents/{agent_id}",
+ "PATCH /gateway/management/controllers/{controller_id}",
+ "PATCH /gateway/packages/{package_id}",
+ "PATCH /gateway/references/reference-types/{type}",
+ "PATCH /gateway/references/{reference_id}",
+ "PATCH /gateway/room-groups/{group_id}",
+ "PATCH /gateway/rooms/{room_id}",
+ "PATCH /gateway/rooms/{room_id}/agents/{agent_id}",
+ "PATCH /gateway/rooms/{room_id}/roles/{name}",
+ "PATCH /gateway/templates/{template_id}",
+ "PATCH /gateway/tenants/{tenant_id}/members/{user_id}",
+ "POST /gateway/agent-sessions/{agent_id}/{session_id}/approvals/{request_id}/answer",
+ "POST /gateway/agents/register",
+ "POST /gateway/agents/register-known-bulk",
+ "POST /gateway/agents/register-other",
+ "POST /gateway/api-keys",
+ "POST /gateway/auth/login",
+ "POST /gateway/auth/logout",
+ "POST /gateway/auth/refresh",
+ "POST /gateway/auth/signup",
+ "POST /gateway/chats",
+ "POST /gateway/chats/{room_id}/archive",
+ "POST /gateway/chats/{room_id}/attachments",
+ "POST /gateway/chats/{room_id}/controls",
+ "POST /gateway/chats/{room_id}/members",
+ "POST /gateway/chats/{room_id}/messages",
+ "POST /gateway/chats/{room_id}/warm",
+ "POST /gateway/collaborations",
+ "POST /gateway/collaborations/{bridge_id}/default",
+ "POST /gateway/collaborations/{bridge_id}/identities",
+ "POST /gateway/collaborations/{bridge_id}/teams/{team_id}",
+ "POST /gateway/connectors",
+ "POST /gateway/documents",
+ "POST /gateway/hosted-machines/ensure",
+ "POST /gateway/hosted-machines/{machine_id}/lifecycle",
+ "POST /gateway/invitations/accept",
+ "POST /gateway/invitations/mine/accept",
+ "POST /gateway/joinable-tenants/{tenant_id}/join",
+ "POST /gateway/management/agents",
+ "POST /gateway/management/controllers",
+ "POST /gateway/management/enrollment-codes",
+ "POST /gateway/management/operations",
+ "POST /gateway/messaging-apps/{platform}/claim",
+ "POST /gateway/messaging-apps/{platform}/install",
+ "POST /gateway/packages",
+ "POST /gateway/packages/{package_id}/documents/{document_id}",
+ "POST /gateway/packages/{package_id}/references/{reference_id}",
+ "POST /gateway/provider-connections/github/flows",
+ "POST /gateway/provider-connections/github/flows/{flow_id}/complete",
+ "POST /gateway/provider-connections/github/flows/{flow_id}/confirm",
+ "POST /gateway/references",
+ "POST /gateway/references/reference-types",
+ "POST /gateway/room-groups",
+ "POST /gateway/rooms/bulk-archive",
+ "POST /gateway/rooms/bulk-delete",
+ "POST /gateway/rooms/from-template",
+ "POST /gateway/rooms/from-template-document",
+ "POST /gateway/rooms/from-yaml",
+ "POST /gateway/rooms/{room_id}/agents",
+ "POST /gateway/rooms/{room_id}/archive",
+ "POST /gateway/rooms/{room_id}/documents/{document_id}",
+ "POST /gateway/rooms/{room_id}/linked-rooms",
+ "POST /gateway/rooms/{room_id}/packages/{package_id}",
+ "POST /gateway/rooms/{room_id}/references/{reference_id}",
+ "POST /gateway/rooms/{room_id}/roles",
+ "POST /gateway/rooms/{room_id}/unarchive",
+ "POST /gateway/rooms/{room_id}/users",
+ "POST /gateway/service-connections/{service}/flows",
+ "POST /gateway/service-connections/{service}/flows/{flow_id}/complete",
+ "POST /gateway/service-connections/{service}/flows/{flow_id}/confirm",
+ "POST /gateway/template-runs/{root_room_id}/continue",
+ "POST /gateway/template-runs/{root_room_id}/stop",
+ "POST /gateway/templates",
+ "POST /gateway/templates/validate",
+ "POST /gateway/tenants",
+ "POST /gateway/tenants/{tenant_id}/budgets",
+ "POST /gateway/tenants/{tenant_id}/invitations",
+ "POST /gateway/tenants/{tenant_id}/join-domains",
+ "POST /gateway/tenants/{tenant_id}/switch",
+ "POST /gateway/users",
+ "PUT /gateway/agents/{agent_id}/addressing-policy",
+ "PUT /gateway/agents/{agent_id}/can-manage-agents",
+ "PUT /gateway/agents/{agent_id}/description",
+ "PUT /gateway/agents/{agent_id}/display-name",
+ "PUT /gateway/agents/{agent_id}/icon",
+ "PUT /gateway/agents/{agent_id}/service-grants/{service}",
+ "PUT /gateway/auth/me/password",
+ "PUT /gateway/chats/{room_id}/hidden",
+ "PUT /gateway/management/agents/{agent_id}",
+ "PUT /gateway/management/controllers/{controller_id}/provider-logins/{provider}",
+ "PUT /gateway/room-groups/{group_id}/rooms",
+ "PUT /gateway/rooms/{room_id}/group",
+ "PUT /gateway/rooms/{room_id}/observe",
+ "PUT /gateway/rooms/{room_id}/protection",
+ "PUT /gateway/service-connections/{service}/key",
+ "PUT /gateway/tenants/{tenant_id}/budgets/{budget_id}",
+ "PUT /gateway/trust-settings"
+ ]
+}
diff --git a/console/tooling-e2e/surface/server-surface.json b/console/tooling-e2e/surface/server-surface.json
new file mode 100644
index 000000000..ee4c8657d
--- /dev/null
+++ b/console/tooling-e2e/surface/server-surface.json
@@ -0,0 +1,1041 @@
+{
+ "_generated": "by scripts/e2e_surface.py; do not edit. Run `just e2e-surface`.",
+ "operations": [
+ "accept_task",
+ "add_users_to_room",
+ "archive_room",
+ "assume_role",
+ "attach_reference_to_room",
+ "cancel_task",
+ "connect_to_room",
+ "create_agent",
+ "create_reference",
+ "create_room",
+ "create_room_document",
+ "create_room_from_yaml",
+ "create_room_group",
+ "define_role",
+ "delegate_task",
+ "delete_role",
+ "delete_room_document",
+ "delete_template",
+ "edit_role",
+ "finalise_task",
+ "get_advanced_config",
+ "get_agent_detail",
+ "get_role_detail",
+ "get_room_detail",
+ "get_room_group_detail",
+ "get_template",
+ "get_template_guide",
+ "invite_agent_to_room",
+ "link_rooms",
+ "list_agents",
+ "list_all_references",
+ "list_all_rooms",
+ "list_bridges",
+ "list_linked_rooms",
+ "list_machines",
+ "list_managed_agents",
+ "list_participants",
+ "list_reference_types",
+ "list_references",
+ "list_roles",
+ "list_room_groups",
+ "list_rooms",
+ "list_tasks",
+ "list_templates",
+ "load_internal_documents",
+ "post_message",
+ "read_context",
+ "release_role",
+ "run_template",
+ "save_template",
+ "send_targeted_message",
+ "unarchive_room",
+ "unlink_rooms",
+ "update_agent_detail",
+ "update_room",
+ "update_room_document",
+ "update_task",
+ "update_template"
+ ],
+ "gatewayRoutes": [
+ {
+ "route": "DELETE /gateway/agents/by-name/{agent_name}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/agents/{agent_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/agents/{agent_id}/service-grants/{service}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/api-keys/{key_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/chats/{room_id}/hidden",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/chats/{room_id}/members/{member_user_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/collaborations/{bridge_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/collaborations/{bridge_id}/identities/{external_user_row_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/collaborations/{bridge_id}/teams/{team_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/connectors/{connector_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/documents/{document_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/management/agents/{agent_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/management/controllers/{controller_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/management/controllers/{controller_id}/provider-logins/{provider}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/messaging-apps/installs/{install_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/packages/{package_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/packages/{package_id}/documents/{document_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/packages/{package_id}/references/{reference_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/provider-connections/github",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/provider-connections/github/flows/{flow_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/references/reference-types/{type}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/references/{reference_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/room-groups/{group_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/rooms/{room_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/rooms/{room_id}/agents/{agent_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/rooms/{room_id}/documents/{document_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/rooms/{room_id}/linked-rooms/{target_room_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/rooms/{room_id}/packages/{package_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/rooms/{room_id}/references/{reference_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/rooms/{room_id}/roles/{name}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/service-connections/{service}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/service-connections/{service}/flows/{flow_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/templates/{template_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/tenants/{tenant_id}/budgets/{budget_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/tenants/{tenant_id}/invitations/{invitation_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/tenants/{tenant_id}/join-domains/{domain}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/tenants/{tenant_id}/members/{user_id}",
+ "auth": "session"
+ },
+ {
+ "route": "DELETE /gateway/trust-settings",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/agent-sessions/approvals",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/agents",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/agents/avatar-settings",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/agents/icon-choices",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/agents/known-types",
+ "auth": "none"
+ },
+ {
+ "route": "GET /gateway/agents/{agent_id}",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/agents/{agent_id}/service-grants",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/api-keys",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/api-keys/{key_id}/reveal",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/auth/config",
+ "auth": "none"
+ },
+ {
+ "route": "GET /gateway/auth/me",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/auth/me/identities",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/auth/oidc/callback",
+ "auth": "none"
+ },
+ {
+ "route": "GET /gateway/auth/oidc/login",
+ "auth": "none"
+ },
+ {
+ "route": "GET /gateway/auth/session",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/chats",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/chats/activity/events",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/chats/events",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/chats/{room_id}/activity",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/chats/{room_id}/media",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/chats/{room_id}/members",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/chats/{room_id}/messages",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/collaborations",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/collaborations/types",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/collaborations/{bridge_id}/directory",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/collaborations/{bridge_id}/teams",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/collaborations/{bridge_id}/teams-package",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/collaborations/{bridge_id}/users",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/connectors",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/connectors/types",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/connectors/{connector_id}",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/docs",
+ "auth": "none"
+ },
+ {
+ "route": "GET /gateway/docs/oauth2-redirect",
+ "auth": "none"
+ },
+ {
+ "route": "GET /gateway/documents",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/documents/{document_id}",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/documents/{document_id}/rooms",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/ecosystem/graph",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/feature-flags",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/hosted-controller/machines",
+ "auth": "operator-token"
+ },
+ {
+ "route": "GET /gateway/hosted-machines",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/hosted-machines/{machine_id}",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/invitations/mine",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/joinable-tenants",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/linked-rooms/graph",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/management/advanced-config",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/management/agents",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/management/agents/{agent_id}",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/management/controllers",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/management/controllers/{controller_id}/provider-logins",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/management/operations",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/management/providers",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/messaging-apps",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/messaging-apps/installs",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/openapi.json",
+ "auth": "none"
+ },
+ {
+ "route": "GET /gateway/packages",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/packages/{package_id}",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/packages/{package_id}/documents",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/packages/{package_id}/references",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/packages/{package_id}/rooms",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/provider-connections/catalog",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/provider-connections/github",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/provider-connections/github/authorize",
+ "auth": "none"
+ },
+ {
+ "route": "GET /gateway/provider-connections/github/callback",
+ "auth": "none"
+ },
+ {
+ "route": "GET /gateway/provider-connections/github/flows/{flow_id}",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/redoc",
+ "auth": "none"
+ },
+ {
+ "route": "GET /gateway/references",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/references/reference-types",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/references/reference-types/owned",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/references/{reference_id}",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/references/{reference_id}/rooms",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/room-groups",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/rooms",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/rooms/template-schema",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/rooms/{room_id}",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/rooms/{room_id}/documents",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/rooms/{room_id}/documents/{document_id}",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/rooms/{room_id}/linked-rooms",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/rooms/{room_id}/linked-rooms/inbound",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/rooms/{room_id}/packages",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/rooms/{room_id}/references",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/rooms/{room_id}/roles",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/rooms/{room_id}/yaml",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/service-connections",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/service-connections/{service}/flows/authorize",
+ "auth": "none"
+ },
+ {
+ "route": "GET /gateway/service-connections/{service}/flows/callback",
+ "auth": "none"
+ },
+ {
+ "route": "GET /gateway/service-connections/{service}/flows/{flow_id}",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/template-runs",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/templates",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/templates/{template_id}",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/templates/{template_id}/content",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/tenants",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/tenants/current",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/tenants/{tenant_id}/audit-events",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/tenants/{tenant_id}/budgets",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/tenants/{tenant_id}/invitations",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/tenants/{tenant_id}/join-domains",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/tenants/{tenant_id}/members",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/tenants/{tenant_id}/usage",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/trust-settings",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/users",
+ "auth": "session"
+ },
+ {
+ "route": "GET /gateway/version",
+ "auth": "session"
+ },
+ {
+ "route": "PATCH /gateway/agents/{agent_id}/options",
+ "auth": "session"
+ },
+ {
+ "route": "PATCH /gateway/collaborations/{bridge_id}",
+ "auth": "session"
+ },
+ {
+ "route": "PATCH /gateway/documents/{document_id}",
+ "auth": "session"
+ },
+ {
+ "route": "PATCH /gateway/management/agents/{agent_id}",
+ "auth": "session"
+ },
+ {
+ "route": "PATCH /gateway/management/controllers/{controller_id}",
+ "auth": "session"
+ },
+ {
+ "route": "PATCH /gateway/packages/{package_id}",
+ "auth": "session"
+ },
+ {
+ "route": "PATCH /gateway/references/reference-types/{type}",
+ "auth": "session"
+ },
+ {
+ "route": "PATCH /gateway/references/{reference_id}",
+ "auth": "session"
+ },
+ {
+ "route": "PATCH /gateway/room-groups/{group_id}",
+ "auth": "session"
+ },
+ {
+ "route": "PATCH /gateway/rooms/{room_id}",
+ "auth": "session"
+ },
+ {
+ "route": "PATCH /gateway/rooms/{room_id}/agents/{agent_id}",
+ "auth": "session"
+ },
+ {
+ "route": "PATCH /gateway/rooms/{room_id}/roles/{name}",
+ "auth": "session"
+ },
+ {
+ "route": "PATCH /gateway/templates/{template_id}",
+ "auth": "session"
+ },
+ {
+ "route": "PATCH /gateway/tenants/{tenant_id}/members/{user_id}",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/agent-sessions/{agent_id}/{session_id}/approvals/{request_id}/answer",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/agents/register",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/agents/register-known-bulk",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/agents/register-other",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/api-keys",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/auth/login",
+ "auth": "none"
+ },
+ {
+ "route": "POST /gateway/auth/logout",
+ "auth": "none"
+ },
+ {
+ "route": "POST /gateway/auth/refresh",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/auth/signup",
+ "auth": "none"
+ },
+ {
+ "route": "POST /gateway/chats",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/chats/{room_id}/archive",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/chats/{room_id}/attachments",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/chats/{room_id}/controls",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/chats/{room_id}/members",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/chats/{room_id}/messages",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/chats/{room_id}/warm",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/collaborations",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/collaborations/{bridge_id}/default",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/collaborations/{bridge_id}/identities",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/collaborations/{bridge_id}/teams/{team_id}",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/connectors",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/documents",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/hosted-controller/machines/{machine_id}/observation",
+ "auth": "operator-token"
+ },
+ {
+ "route": "POST /gateway/hosted-controller/machines/{machine_id}/prepare",
+ "auth": "operator-token"
+ },
+ {
+ "route": "POST /gateway/hosted-machines/ensure",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/hosted-machines/{machine_id}/lifecycle",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/invitations/accept",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/invitations/mine/accept",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/joinable-tenants/{tenant_id}/join",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/management/agents",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/management/controllers",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/management/enrollment-codes",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/management/operations",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/messaging-apps/{platform}/claim",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/messaging-apps/{platform}/install",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/packages",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/packages/{package_id}/documents/{document_id}",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/packages/{package_id}/references/{reference_id}",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/provider-connections/github/callback",
+ "auth": "none"
+ },
+ {
+ "route": "POST /gateway/provider-connections/github/flows",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/provider-connections/github/flows/{flow_id}/complete",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/provider-connections/github/flows/{flow_id}/confirm",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/references",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/references/reference-types",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/room-groups",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/rooms",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/rooms/bulk-archive",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/rooms/bulk-delete",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/rooms/from-template",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/rooms/from-template-document",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/rooms/from-yaml",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/rooms/{room_id}/agents",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/rooms/{room_id}/archive",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/rooms/{room_id}/documents/{document_id}",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/rooms/{room_id}/linked-rooms",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/rooms/{room_id}/packages/{package_id}",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/rooms/{room_id}/references/{reference_id}",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/rooms/{room_id}/roles",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/rooms/{room_id}/unarchive",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/rooms/{room_id}/users",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/service-connections/{service}/flows",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/service-connections/{service}/flows/callback",
+ "auth": "none"
+ },
+ {
+ "route": "POST /gateway/service-connections/{service}/flows/{flow_id}/complete",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/service-connections/{service}/flows/{flow_id}/confirm",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/template-runs/{root_room_id}/continue",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/template-runs/{root_room_id}/stop",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/templates",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/templates/validate",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/tenants",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/tenants/{tenant_id}/budgets",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/tenants/{tenant_id}/invitations",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/tenants/{tenant_id}/join-domains",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/tenants/{tenant_id}/switch",
+ "auth": "session"
+ },
+ {
+ "route": "POST /gateway/users",
+ "auth": "session"
+ },
+ {
+ "route": "PUT /gateway/agents/{agent_id}/addressing-policy",
+ "auth": "session"
+ },
+ {
+ "route": "PUT /gateway/agents/{agent_id}/can-manage-agents",
+ "auth": "session"
+ },
+ {
+ "route": "PUT /gateway/agents/{agent_id}/description",
+ "auth": "session"
+ },
+ {
+ "route": "PUT /gateway/agents/{agent_id}/display-name",
+ "auth": "session"
+ },
+ {
+ "route": "PUT /gateway/agents/{agent_id}/icon",
+ "auth": "session"
+ },
+ {
+ "route": "PUT /gateway/agents/{agent_id}/service-grants/{service}",
+ "auth": "session"
+ },
+ {
+ "route": "PUT /gateway/auth/me/password",
+ "auth": "session"
+ },
+ {
+ "route": "PUT /gateway/chats/{room_id}/hidden",
+ "auth": "session"
+ },
+ {
+ "route": "PUT /gateway/management/agents/{agent_id}",
+ "auth": "session"
+ },
+ {
+ "route": "PUT /gateway/management/controllers/{controller_id}/provider-logins/{provider}",
+ "auth": "session"
+ },
+ {
+ "route": "PUT /gateway/room-groups/{group_id}/rooms",
+ "auth": "session"
+ },
+ {
+ "route": "PUT /gateway/rooms/{room_id}/group",
+ "auth": "session"
+ },
+ {
+ "route": "PUT /gateway/rooms/{room_id}/observe",
+ "auth": "session"
+ },
+ {
+ "route": "PUT /gateway/rooms/{room_id}/protection",
+ "auth": "session"
+ },
+ {
+ "route": "PUT /gateway/service-connections/{service}/key",
+ "auth": "session"
+ },
+ {
+ "route": "PUT /gateway/tenants/{tenant_id}/budgets/{budget_id}",
+ "auth": "session"
+ },
+ {
+ "route": "PUT /gateway/trust-settings",
+ "auth": "session"
+ }
+ ]
+}
diff --git a/core/tests/test_e2e_surface.py b/core/tests/test_e2e_surface.py
new file mode 100644
index 000000000..4218578ea
--- /dev/null
+++ b/core/tests/test_e2e_surface.py
@@ -0,0 +1,68 @@
+"""The surface snapshot the end-to-end coverage gate reads.
+
+`scripts/e2e_surface.py --check` already fails CI when the committed snapshot
+and the server disagree. These tests pin what the snapshot means: which routes
+count as taking a session, that flag-gated routes are in it, and that a
+setting in the environment cannot change what it says.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+def _load_exporter() -> ModuleType:
+ """Import scripts/e2e_surface.py, which is not an installed package."""
+ path = REPO_ROOT / "scripts" / "e2e_surface.py"
+ spec = importlib.util.spec_from_file_location("e2e_surface", path)
+ assert spec is not None and spec.loader is not None
+ module = importlib.util.module_from_spec(spec)
+ sys.modules[spec.name] = module
+ spec.loader.exec_module(module)
+ return module
+
+
+surface = _load_exporter()
+
+
+def _routes() -> dict[str, str]:
+ rendered = json.loads(surface.render())
+ return {entry["route"]: entry["auth"] for entry in rendered["gatewayRoutes"]}
+
+
+def test_routes_are_classified_by_what_they_authenticate_with() -> None:
+ routes = _routes()
+ assert routes["POST /gateway/rooms"] == "session"
+ # Before a tenant is chosen: authenticated, with no tenant bound.
+ assert routes["GET /gateway/tenants"] == "session"
+ assert routes["POST /gateway/auth/login"] == "none"
+ assert routes["GET /gateway/hosted-controller/machines"] == "operator-token"
+
+
+def test_flag_gated_routes_are_included() -> None:
+ routes = _routes()
+ assert "POST /gateway/management/agents" in routes
+ assert "GET /gateway/service-connections" in routes
+
+
+def test_the_environment_does_not_change_the_snapshot(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ before = surface.render()
+ monkeypatch.setenv("FEATURE_FLAGS_ENABLED", "")
+ assert surface.render() == before
+
+
+def test_operations_include_gated_groups() -> None:
+ operations = json.loads(surface.render())["operations"]
+ assert "list_rooms" in operations
+ assert "create_agent" in operations
+ assert operations == sorted(operations)
diff --git a/justfile b/justfile
index cdb5b148a..2cb1eb8ec 100644
--- a/justfile
+++ b/justfile
@@ -176,6 +176,15 @@ e2e-fast *args:
e2e-provider *args:
SWITCH_E2E_LANE=provider console/tooling-e2e/scripts/ephemeral-stack.sh {{ args }}
+# ── Regenerate the server surface the E2E coverage gate reads ─────────────────
+# Every agent operation and gateway route, written to
+# console/tooling-e2e/surface/server-surface.json. CI fails when it is stale;
+# after regenerating, the gate (pnpm test in console/tooling-e2e) says what a
+# new operation or route needs: a scenario, or an exemption with its reason.
+# Regenerate the server surface snapshot the E2E coverage gate reads
+e2e-surface:
+ uv run --project core python scripts/e2e_surface.py
+
# ── Run integration tests (real Postgres via testcontainers) ───────────────────
# DOCKER_HOST is auto-resolved from the active docker context in conftest, so this
# works under Docker Desktop / OrbStack / colima without extra setup.
diff --git a/scripts/e2e_surface.py b/scripts/e2e_surface.py
new file mode 100644
index 000000000..5d0f08f5f
--- /dev/null
+++ b/scripts/e2e_surface.py
@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""Write, or check, the server surface the end-to-end coverage gate reads.
+
+The gate (`console/tooling-e2e/src/gate/`) holds every agent operation and
+every gateway route to account: a scenario that covers it, or an exemption
+that says why not. The gate is TypeScript and must not need a running server,
+so the surface it reads is a committed snapshot:
+
+* every declared agent operation, gated groups included — one definition
+ serves both the MCP server and the HTTP front door, so this is the agent
+ surface whichever door an agent uses;
+* every gateway route as `METHOD /gateway/path`, with every feature flag on and
+ agent management mounted, and what it authenticates with: a signed-in
+ session (`session`), the hosted controller's operator token
+ (`operator-token`), or nothing (`none`). The gate requires each route that
+ takes nothing to be listed with a reason, and the fast lane checks that each
+ `session` route refuses a request without one.
+
+Usage:
+ uv run --project core python scripts/e2e_surface.py # write it
+ uv run --project core python scripts/e2e_surface.py --check # verify it
+
+`--check` builds the snapshot in memory and compares, so CI catches both a
+route added without regenerating and a hand-edited snapshot.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Callable, Iterator
+from pathlib import Path
+from typing import Any
+from unittest.mock import MagicMock
+
+from fastapi import FastAPI
+from fastapi.dependencies.models import Dependant
+from fastapi.routing import APIRoute
+from starlette.routing import Route
+
+from switch_core.bridges.agent.operations import declared_operations
+from switch_core.config import SwitchConfig
+from switch_core.feature_flags import KNOWN_FEATURE_FLAGS
+from switch_core.gateway.app import create_gateway_app
+from switch_core.gateway.auth import (
+ get_authenticated_caller,
+ get_authenticated_session,
+ get_authenticated_user_id,
+ get_current_user,
+ get_current_user_in_transaction,
+)
+from switch_core.gateway.hosted_controller import controller_session
+from switch_core.management.gateway_routes import router as management_router
+from switch_core.management.wiring import GATEWAY_PREFIX
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SNAPSHOT = REPO_ROOT / "console" / "tooling-e2e" / "surface" / "server-surface.json"
+
+# Every dependency that reads the `switch_auth` session cookie and refuses a
+# request without a valid one. A route that depends on any of them, however
+# deep, takes a signed-in session.
+SESSION_DEPENDENCIES: frozenset[Callable[..., Any]] = frozenset(
+ {
+ get_current_user,
+ get_current_user_in_transaction,
+ get_authenticated_user_id,
+ get_authenticated_session,
+ get_authenticated_caller,
+ }
+)
+
+# The app's collaborators are never called: building the app only mounts its
+# routers. Its configuration is real, so whatever routes a setting gates are
+# decided as a deployment would decide them, and fixed here rather than read
+# from the environment, so every machine writes the same snapshot.
+_COLLABORATORS = (
+ "agent_store",
+ "room_store",
+ "room_group_store",
+ "room_service",
+ "chat_service",
+ "bridge_store",
+ "client_lifecycle",
+ "collab_lifecycle",
+ "connector_lifecycle",
+ "connector_store",
+ "event_buffer",
+ "session_factory",
+ "user_store",
+ "external_user_store",
+ "api_key_store",
+ "invitation_store",
+ "join_domain_store",
+ "template_store",
+ "usage_store",
+ "budget_store",
+ "resource_service",
+ "protocol",
+)
+
+
+def _config() -> SwitchConfig:
+ return SwitchConfig(
+ _env_file=None, # type: ignore[call-arg]
+ db_host="db",
+ db_port="5432",
+ db_user="switch",
+ db_password="placeholder",
+ db_name="switch",
+ id_server_name="switch.local",
+ agent_registration_token="placeholder",
+ secret_keys="surface:" + "0" * 64,
+ gateway_admin_email="[email protected]",
+ gateway_admin_password="placeholder",
+ controller_token_secret="0" * 64,
+ feature_flags_enabled=",".join(sorted(KNOWN_FEATURE_FLAGS)),
+ )
+
+
+def gateway_app() -> FastAPI:
+ app = create_gateway_app(
+ **{name: MagicMock() for name in _COLLABORATORS},
+ install_service=None,
+ invite_mailer=None,
+ config=_config(),
+ )
+ # What `Management.install` mounts when the agent_management flag is on.
+ app.include_router(management_router, prefix=GATEWAY_PREFIX)
+ return app
+
+
+def _dependency_calls(dependant: Dependant) -> Iterator[Callable[..., Any]]:
+ for dependency in dependant.dependencies:
+ if dependency.call is not None:
+ yield dependency.call
+ yield from _dependency_calls(dependency)
+
+
+# The hosted controller's machine routes take the operator controller's bearer
+# token instead, and are never reachable with a session.
+OPERATOR_TOKEN_DEPENDENCIES: frozenset[Callable[..., Any]] = frozenset(
+ {controller_session}
+)
+
+
+def _auth(route: Route) -> str:
+ if not isinstance(route, APIRoute):
+ return "none"
+ calls = set(_dependency_calls(route.dependant))
+ if calls & SESSION_DEPENDENCIES:
+ return "session"
+ if calls & OPERATOR_TOKEN_DEPENDENCIES:
+ return "operator-token"
+ return "none"
+
+
+def gateway_routes(app: FastAPI) -> list[dict[str, str]]:
+ routes: dict[str, str] = {}
+ for route in app.routes:
+ if not isinstance(route, Route):
+ raise TypeError(
+ f"Gateway route {route!r} is a {type(route).__name__}, which this "
+ "snapshot cannot enumerate. Teach scripts/e2e_surface.py about it."
+ )
+ for method in sorted(route.methods or ()):
+ if method == "HEAD":
+ continue
+ key = f"{method} /gateway{route.path}"
+ if key in routes:
+ raise ValueError(f"Gateway route {key} is mounted twice.")
+ routes[key] = _auth(route)
+ return [{"route": key, "auth": routes[key]} for key in sorted(routes)]
+
+
+def render() -> str:
+ surface = {
+ "_generated": "by scripts/e2e_surface.py; do not edit. Run `just e2e-surface`.",
+ "operations": sorted(declared_operations()),
+ "gatewayRoutes": gateway_routes(gateway_app()),
+ }
+ return json.dumps(surface, indent=2) + "\n"
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--check", action="store_true", help="verify, write nothing")
+ args = parser.parse_args()
+
+ expected = render()
+ relative = SNAPSHOT.relative_to(REPO_ROOT)
+ if args.check:
+ actual = SNAPSHOT.read_text() if SNAPSHOT.exists() else None
+ if actual != expected:
+ print(
+ f"{relative} is out of date: the server's operations or gateway "
+ "routes changed without regenerating it, or it was edited by "
+ "hand.\nRun `just e2e-surface` and commit the result; the "
+ "end-to-end coverage gate then says what the change needs.",
+ file=sys.stderr,
+ )
+ return 1
+ print(f"{relative} is current.")
+ return 0
+ SNAPSHOT.parent.mkdir(parents=True, exist_ok=True)
+ SNAPSHOT.write_text(expected)
+ print(f"wrote {relative}")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())