Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
E2E coverage gate over agent operations and gateway routes
Petr Bauch4c26a5c8c9b9
diff --git a/.github/workflows/pr-ci.yml b/.github/workflows/pr-ci.ymlindex 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: mypyrun: 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 rundiff --git a/console/tooling-e2e/README.md b/console/tooling-e2e/README.mdindex 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 environmentdiff --git a/console/tooling-e2e/src/clients/switch-client.ts b/console/tooling-e2e/src/clients/switch-client.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.pynew file mode 100644index 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/justfileindex 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.pynew file mode 100644index 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())