@stage-labs/metro 0.1.0-beta.3 → 0.1.0-beta.300

package/runtime/node_modules/@metro-labs/daemon/src/connectors/migration-state.ts

@@ -0,0 +1,142 @@
+import { randomBytes } from 'node:crypto';
+import { closeSync, existsSync, fsyncSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isRecord } from '@metro-labs/core/is-record';
+import { parseId } from '@metro-labs/core/ids';
+import { ensureSecureDir } from '@metro-labs/core/secure-fs';
+import { ApiError } from '@metro-labs/http/api-error';
+import { connectorPolicyOf, type ConnectorPolicy } from '@metro-labs/http/connector-delivery';
+import { publicOAuthResource } from '@metro-labs/http/connector-public-url';
+import { agentsDir } from '../agents/files.js';
+import { captureMigrationOperations } from './migration-operations.js';
+
+export type MigrationPhase = 'recovering' | 'freezing' | 'preparing' | 'prepared' | 'cutover' | 'active' | 'rollback' | 'rolled_back';
+export type MigrationAuth = 'none' | 'header' | 'oauth';
+
+export interface MigrationRecord {
+  id: string;
+  owner: string;
+  agentId: string;
+  keyId: string;
+  sourceId: string;
+  name: string;
+  destinationId: string | null;
+  phase: MigrationPhase;
+  auth: MigrationAuth;
+  oauthResource?: string;
+  move?: boolean;
+  grantImported?: boolean;
+  captured?: boolean;
+  recoveryReceipt?: string;
+  sourceStamp: string;
+  policy: ConnectorPolicy;
+  reason: string | null;
+}
+
+const phases: readonly MigrationPhase[] = ['recovering', 'freezing', 'preparing', 'prepared', 'cutover', 'active', 'rollback', 'rolled_back'];
+const auths: readonly MigrationAuth[] = ['none', 'header', 'oauth'];
+const fields = ['id', 'owner', 'agentId', 'keyId', 'sourceId', 'name', 'destinationId', 'phase', 'auth', 'oauthResource', 'sourceStamp', 'policy', 'reason', 'move', 'grantImported', 'captured', 'recoveryReceipt'];
+const unavailable = (): ApiError => new ApiError('Protected connector migration records cannot be read. Restore their file or permissions before using connectors.', 503);
+const DIGEST = /^[A-Za-z0-9_-]{43}$/;
+const pathOf = (dir: string): string => join(dir, 'connector-migrations.json');
+const markerOf = (dir: string): string => join(dir, 'connector-migrations.initialized');
+
+function requiredId(value: unknown): string {
+  const id = parseId(value);
+  if (id === null) throw unavailable();
+  return id;
+}
+
+function field(value: unknown, pattern: RegExp): string {
+  if (typeof value !== 'string' || !pattern.test(value)) throw unavailable();
+  return value;
+}
+
+function movementOf(value: Record<string, unknown>): Pick<MigrationRecord, 'move' | 'grantImported' | 'captured' | 'recoveryReceipt'> {
+  const result: Pick<MigrationRecord, 'move' | 'grantImported' | 'captured' | 'recoveryReceipt'> = {};
+  for (const key of ['move', 'grantImported', 'captured'] as const) {
+    const flag = value[key];
+    if (flag === undefined) continue;
+    if (typeof flag !== 'boolean') throw unavailable();
+    result[key] = flag;
+  }
+  if (value.recoveryReceipt !== undefined) result.recoveryReceipt = field(value.recoveryReceipt, /^[a-f0-9]{64}$/);
+  return result;
+}
+
+function recordOf(value: unknown): MigrationRecord {
+  if (!isRecord(value) || Object.keys(value).some((key) => !fields.includes(key))) throw unavailable();
+  const phase = phases.find((item) => item === value.phase);
+  const auth = auths.find((item) => item === value.auth);
+  if (phase === undefined || auth === undefined || (value.oauthResource !== undefined && auth !== 'oauth')) throw unavailable();
+  return {
+    ...movementOf(value),
+    ...(value.oauthResource === undefined ? {} : { oauthResource: publicOAuthResource(value.oauthResource) }),
+    id: requiredId(value.id), sourceId: requiredId(value.sourceId), agentId: requiredId(value.agentId),
+    owner: field(value.owner, /^org_[A-Za-z0-9]{1,128}$/), keyId: field(value.keyId, DIGEST), sourceStamp: field(value.sourceStamp, DIGEST),
+    name: field(value.name, /^.{1,200}$/), destinationId: value.destinationId === null ? null : requiredId(value.destinationId),
+    phase, auth, policy: connectorPolicyOf(value.policy), reason: value.reason === null ? null : field(value.reason, /^[a-z_]{1,64}$/),
+  };
+}
+
+function recordsOf(text: string): MigrationRecord[] {
+  const value: unknown = JSON.parse(text);
+  if (!isRecord(value) || value.version !== 1 || !Array.isArray(value.records) || value.records.length > 500) throw unavailable();
+  const records = value.records.map(recordOf);
+  if (new Set(records.map((record) => record.sourceId)).size !== records.length) throw unavailable();
+  return records;
+}
+
+export function migrationRecords(dir = agentsDir()): MigrationRecord[] {
+  try {
+    const marked = existsSync(markerOf(dir));
+    if (marked && readFileSync(markerOf(dir), 'utf8') !== '1\n') throw unavailable();
+    if (!existsSync(pathOf(dir))) {
+      if (marked) throw unavailable();
+      return [];
+    }
+    if (!marked) throw unavailable();
+    return recordsOf(readFileSync(pathOf(dir), 'utf8'));
+  } catch {
+    throw unavailable();
+  }
+}
+
+export function migrationRecord(id: string, dir = agentsDir()): MigrationRecord | null {
+  return migrationRecords(dir).find((record) => record.sourceId === id) ?? null;
+}
+
+function flush(path: string): void {
+  const fd = openSync(path, 'r');
+  try { fsyncSync(fd); } finally { closeSync(fd); }
+}
+
+function markInitialized(dir: string): void {
+  const path = markerOf(dir);
+  if (existsSync(path)) return;
+  writeFileSync(path, '1\n', { flag: 'wx', mode: 0o600 });
+  flush(path);
+  flush(dir);
+}
+
+export function saveMigration(record: MigrationRecord, dir = agentsDir()): void {
+  const valid = recordOf(record);
+  const previous = migrationRecords(dir);
+  const rows = previous.filter((row) => row.sourceId !== valid.sourceId);
+  if (rows.length >= 500) throw new ApiError('There are too many connector migrations on this agent.', 409);
+  rows.push(valid);
+  ensureSecureDir(dir);
+  markInitialized(dir);
+  captureMigrationOperations(valid.sourceId, dir, !previous.some((row) => row.sourceId === valid.sourceId));
+  const path = pathOf(dir);
+  const temporary = `${path}.${randomBytes(12).toString('hex')}.tmp`;
+  const fd = openSync(temporary, 'wx', 0o600);
+  try {
+    try {
+      writeFileSync(fd, `${JSON.stringify({ version: 1, records: rows })}\n`);
+      fsyncSync(fd);
+    } finally { closeSync(fd); }
+    renameSync(temporary, path);
+    flush(dir);
+  } finally { rmSync(temporary, { force: true }); }
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/migration-url.ts

@@ -0,0 +1,9 @@
+import { parsePublicConnectorUrl } from '@metro-labs/http/connector-public-url';
+
+export function migrationOrigin(raw: unknown): string | null {
+  try {
+    return parsePublicConnectorUrl(raw).origin;
+  } catch {
+    return null;
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/oauth-routes.ts

@@ -0,0 +1,178 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { errMsg, log } from '@metro-labs/core/log';
+import { bodyField, readJsonBody, sendJson, stringOf } from '@metro-labs/http/api-http';
+import {
+  beginOAuth,
+  completeOAuth,
+  prepareOAuth,
+  takePending,
+  type PendingAuth,
+} from './oauth.js';
+import { connectorClient, connectorName } from '@metro-labs/http/connector-input';
+import { parseConnectorUrl } from '@metro-labs/http/connector-url';
+import type { OAuthAuth } from '@metro-labs/http/connector-mcp';
+import type { Connector, PendingConnectorInput } from './store.js';
+import { agentsDir } from '../agents/files.js';
+import { withLocalMigrationOperation } from './migration-guard.js';
+import { migrationRecord } from './migration-state.js';
+import { ApiError } from '@metro-labs/http/api-error';
+
+export function hostOf(url: string): string {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return '';
+  }
+}
+
+export interface OAuthRouteDeps {
+  migrationDir?: string;
+  createPendingConnector: (input: PendingConnectorInput) => Promise<Connector>;
+  reconnectConnector: (id: string, auth: OAuthAuth) => Promise<Connector>;
+  getConnector: (id: string) => Promise<Connector>;
+}
+
+export async function startOAuth(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: OAuthRouteDeps,
+  body: unknown,
+  payload: (row: Connector) => Record<string, unknown>,
+): Promise<void> {
+  const name = connectorName(bodyField(body, 'name'));
+  await withLocalMigrationOperation('', deps.migrationDir ?? agentsDir(), async (operation) => {
+    const url = parseConnectorUrl(bodyField(body, 'url'));
+    const returnTo = stringOf(bodyField(body, 'returnTo'));
+    const clientId = bodyField(body, 'clientId');
+    const clientSecret = bodyField(body, 'clientSecret');
+    const prepared = await prepareOAuth({
+      url,
+      client: connectorClient(clientId, clientSecret),
+      returnTo,
+    }, operation.fetch);
+    const row = await deps.createPendingConnector({
+      name,
+      url: bodyField(body, 'url'),
+      clientId,
+      clientSecret,
+    });
+    operation.check();
+    const authorize = beginOAuth(prepared, {
+      name: row.name,
+      url,
+      returnTo,
+      connectorId: row.id,
+      migrationId: migrationRecord(row.id, deps.migrationDir)?.id ?? null,
+    });
+    log.info(
+      { id: row.id, host: url.hostname },
+      'connector-api: stored unconnected, sending the user to sign in',
+    );
+    sendJson(req, res, 201, { ...payload(row), authorizeUrl: authorize });
+  }, true);
+}
+
+export async function handleConnect(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: OAuthRouteDeps,
+  id: string,
+): Promise<void> {
+  await withLocalMigrationOperation(id, deps.migrationDir ?? agentsDir(), async (operation) => {
+    const row = await deps.getConnector(id);
+    const url = parseConnectorUrl(row.url);
+    const body = await readJsonBody(req);
+    const returnTo = stringOf(bodyField(body, 'returnTo'));
+    const prepared = await prepareOAuth({ url, client: row.client, returnTo }, operation.fetch);
+    operation.check();
+    const authorize = beginOAuth(prepared, {
+      name: row.name,
+      url,
+      returnTo,
+      connectorId: row.id,
+      migrationId: migrationRecord(row.id, deps.migrationDir)?.id ?? null,
+    });
+    log.info(
+      { id: row.id, host: url.hostname },
+      'connector-api: sending the user back to sign in',
+    );
+    sendJson(req, res, 202, { status: 'oauth', authorizeUrl: authorize });
+  }, true);
+}
+
+function landing(entry: PendingAuth, id?: string): string {
+  const target = id ?? entry.connectorId;
+  return target === undefined ? '#/connectors' : `#/connector/${target}`;
+}
+
+function backTo(entry: PendingAuth, error?: string, id?: string): string {
+  const suffix =
+    error === undefined
+      ? ''
+      : `?connector_error=${encodeURIComponent(error)}`;
+  return `${entry.returnTo}${suffix}${landing(entry, id)}`;
+}
+
+function redirect(res: ServerResponse, location: string): void {
+  res.writeHead(302, { location, 'cache-control': 'no-store' }).end();
+}
+
+async function saveOAuth(
+  deps: OAuthRouteDeps,
+  entry: PendingAuth,
+  auth: OAuthAuth,
+): Promise<Connector> {
+  return deps.reconnectConnector(entry.connectorId, auth);
+}
+
+function checkGeneration(entry: PendingAuth, dir: string | undefined): void {
+  if ((entry.migrationId ?? null) !== (migrationRecord(entry.connectorId, dir)?.id ?? null)) throw new ApiError('This sign-in predates the connector migration. Start a fresh sign-in.', 409);
+}
+
+async function settleCallback(
+  res: ServerResponse,
+  deps: OAuthRouteDeps,
+  entry: PendingAuth,
+  code: string,
+): Promise<void> {
+  try {
+    const saved = await withLocalMigrationOperation(entry.connectorId, deps.migrationDir ?? agentsDir(), async (operation) => {
+      checkGeneration(entry, deps.migrationDir);
+      const auth = await completeOAuth(entry, code, operation.fetch);
+      operation.check();
+      checkGeneration(entry, deps.migrationDir);
+      return saveOAuth(deps, entry, auth);
+    }, true);
+    log.info(
+      { id: saved.id, name: saved.name, host: hostOf(saved.url) },
+      'connector-api: oauth sign-in completed',
+    );
+    redirect(res, backTo(entry, undefined, saved.id));
+  } catch (err) {
+    log.warn({ err: errMsg(err) }, 'connector-api: oauth sign-in failed');
+    redirect(res, backTo(entry, errMsg(err)));
+  }
+}
+
+export function handleCallback(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: OAuthRouteDeps,
+): void {
+  const query = new URLSearchParams((req.url ?? '').split('?')[1] ?? '');
+  const entry = takePending(query.get('state') ?? '');
+  if (entry === undefined) {
+    sendJson(req, res, 400, { error: 'that sign-in has expired — start it again' });
+    return;
+  }
+  const denied = query.get('error');
+  const code = query.get('code') ?? '';
+  if (denied !== null || code === '') {
+    redirect(res, backTo(entry, denied ?? 'no authorization code came back'));
+    return;
+  }
+  settleCallback(res, deps, entry, code).catch((err: unknown) => {
+    log.warn({ err: errMsg(err) }, 'connector-api: oauth callback failed');
+    if (!res.headersSent) redirect(res, backTo(entry, 'sign-in failed'));
+  });
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/oauth.ts

@@ -0,0 +1,171 @@
+import { publicBaseOrDefault } from '../files/attach-serve.js';
+import { refused } from '@metro-labs/http/connector-url';
+import type { OAuthAuth, OAuthTokens } from '@metro-labs/http/connector-mcp';
+import { validateReturnTo } from '@metro-labs/http/return-to';
+import {
+  authorizeUrl,
+  exchangeCode,
+  newVerifier,
+  refreshTokens,
+  registerClient,
+  type OAuthClient,
+} from '@metro-labs/http/connector-oauth';
+import { discoverOAuth, type OAuthServer } from '@metro-labs/http/connector-discovery';
+import { ticketStore } from '@metro-labs/core/tickets';
+import type { FetchLike } from '@metro-labs/core/stations/oauth';
+
+export interface PendingAuth {
+  name: string;
+  url: string;
+  resource: string;
+  returnTo: string;
+  verifier: string;
+  server: OAuthServer;
+  client: OAuthClient;
+  connectorId: string;
+  migrationId?: string | null;
+}
+
+const pending = ticketStore<PendingAuth>(10 * 60_000, 100);
+
+export const startPending = (entry: PendingAuth, now = Date.now()): string => pending.mint(entry, now).ticket;
+
+export const takePending = (state: string, now = Date.now()): PendingAuth | undefined => pending.take(state, now);
+
+export const pendingCount = (): number => pending.size();
+
+const REFRESH_SKEW_MS = 300_000;
+
+const CALLBACK_PATH = '/api/connectors/callback';
+
+const callbackUri = (): string =>
+  `${publicBaseOrDefault()}${CALLBACK_PATH}`;
+
+const resourceOf = (url: URL): string => url.toString();
+
+export interface PrepareInput {
+  url: URL;
+  client: OAuthClient | null;
+  returnTo: string;
+}
+
+export interface PreparedOAuth {
+  server: OAuthServer;
+  client: OAuthClient;
+  redirectUri: string;
+}
+
+export async function prepareOAuth(input: PrepareInput, send: FetchLike = fetch): Promise<PreparedOAuth> {
+  if (!validateReturnTo(input.returnTo))
+    throw refused('that return address is not one Metro will send you back to');
+  const server = await discoverOAuth(input.url, send);
+  const redirectUri = callbackUri();
+  const client = input.client ?? (await registerClient(server, redirectUri, send));
+  return { server, client, redirectUri };
+}
+
+export interface BeginInput {
+  connectorId: string;
+  migrationId?: string | null;
+  name: string;
+  url: URL;
+  returnTo: string;
+}
+
+export function beginOAuth(prepared: PreparedOAuth, input: BeginInput): string {
+  const { server, client, redirectUri } = prepared;
+  const verifier = newVerifier();
+  const resource = resourceOf(input.url);
+  const state = startPending({
+    name: input.name,
+    url: input.url.toString(),
+    resource,
+    returnTo: input.returnTo,
+    verifier,
+    server,
+    client,
+    connectorId: input.connectorId,
+    migrationId: input.migrationId ?? null,
+  });
+  return authorizeUrl({
+    server,
+    client,
+    redirectUri,
+    state,
+    verifier,
+    resource,
+  });
+}
+
+function authOf(pendingAuth: PendingAuth, tokens: OAuthTokens): OAuthAuth {
+  return {
+    kind: 'oauth',
+    issuer: pendingAuth.server.issuer,
+    tokenEndpoint: pendingAuth.server.tokenEndpoint,
+    resource: pendingAuth.resource,
+    clientId: pendingAuth.client.clientId,
+    ...(pendingAuth.client.clientSecret === undefined
+      ? {}
+      : { clientSecret: pendingAuth.client.clientSecret }),
+    ...(pendingAuth.server.scopes.length === 0
+      ? {}
+      : { scope: pendingAuth.server.scopes.join(' ') }),
+    ...tokens,
+  };
+}
+
+export async function completeOAuth(
+  entry: PendingAuth,
+  code: string,
+  send: FetchLike = fetch,
+): Promise<OAuthAuth> {
+  const tokens = await exchangeCode(entry.server, entry.client, {
+    code,
+    redirectUri: callbackUri(),
+    verifier: entry.verifier,
+    resource: entry.resource,
+  }, send);
+  return authOf(entry, tokens);
+}
+
+export function oauthExpired(auth: OAuthAuth, now = Date.now()): boolean {
+  return auth.expiresAt !== undefined && auth.expiresAt - REFRESH_SKEW_MS <= now;
+}
+
+export async function refreshOAuth(
+  auth: OAuthAuth,
+  resource: string,
+  send: FetchLike = fetch,
+): Promise<OAuthAuth> {
+  if (auth.refreshToken === undefined)
+    throw refused('that connector needs signing in again');
+  const server = {
+    issuer: auth.issuer,
+    authorizationEndpoint: '',
+    tokenEndpoint: auth.tokenEndpoint,
+    registrationEndpoint: null,
+    supportsS256: true,
+    scopes: [],
+  };
+  const client = {
+    clientId: auth.clientId,
+    ...(auth.clientSecret === undefined
+      ? {}
+      : { clientSecret: auth.clientSecret }),
+  };
+  const tokens = await refreshTokens(
+    server,
+    client,
+    auth.refreshToken,
+    auth.resource ?? resource,
+    auth.scope,
+    send,
+  );
+  return {
+    ...auth,
+    ...tokens,
+    ...(tokens.refreshToken === undefined
+      ? { refreshToken: auth.refreshToken }
+      : {}),
+  };
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/org-relay.ts

@@ -0,0 +1,61 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { ApiError } from '@metro-labs/http/api-error';
+import { screenCalls, type Screened } from './relay-policy.js';
+import type { RelaySession } from './relay-session.js';
+import type { RelayTarget } from './relay-target.js';
+
+type Ready = Extract<RelayTarget, { kind: 'ok' }>;
+type Forward = (target: Ready, body: Uint8Array<ArrayBuffer> | null, signal: AbortSignal) => Promise<Response>;
+type OrgExchange =
+  | { kind: 'response'; upstream: Response; answers: Record<string, unknown>[] }
+  | { kind: 'blocked'; screened: Screened };
+
+const METHODS = new Set(['initialize', 'ping', 'tools/list', 'tools/call', 'notifications/initialized', 'notifications/cancelled']);
+
+function requestBatch(body: Uint8Array | null): boolean {
+  if (body === null) return false;
+  let parsed: unknown;
+  try { parsed = JSON.parse(new TextDecoder().decode(body)); }
+  catch { throw new ApiError('Invalid organization connector request.', 400); }
+  const batch = Array.isArray(parsed);
+  const entries: unknown[] = Array.isArray(parsed) ? parsed : [parsed];
+  if (entries.length === 0 || entries.some((item) => !validMessage(item))) throw new ApiError('This organization connector accepts MCP tool requests only.', 400);
+  return batch;
+}
+
+function validMessage(item: unknown): boolean {
+  if (!isRecord(item) || item.jsonrpc !== '2.0' || typeof item.method !== 'string' || !METHODS.has(item.method)) return false;
+  if (item.method !== 'tools/call') return true;
+  if (!isRecord(item.params) || typeof item.params.name !== 'string' || item.params.name === '') return false;
+  return item.params.arguments === undefined || isRecord(item.params.arguments);
+}
+
+function ready(session: RelaySession, signal: AbortSignal): Ready {
+  if (signal.aborted) throw new ApiError('This organization connector is no longer available.', 503);
+  const target = session.current();
+  if (target.kind === 'missing') throw new ApiError('No such organization connector.', 404);
+  if (target.kind === 'signin') throw new ApiError('This organization connector needs signing in again.', 424);
+  return target;
+}
+
+export async function exchangeOrg(id: string, session: RelaySession, body: Uint8Array<ArrayBuffer> | null, clientSignal: AbortSignal, forward: Forward): Promise<OrgExchange> {
+  const signal = AbortSignal.any([clientSignal, session.signal]);
+  const batch = requestBatch(body);
+  let pending = body;
+  const answers: Record<string, unknown>[] = [];
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    await session.target(attempt > 0);
+    ready(session, signal);
+    const screened = pending === null ? null : screenCalls(pending, id, session.blocker());
+    if (screened !== null) {
+      answers.push(...screened.answers);
+      pending = screened.forward;
+      if (pending === null) return { kind: 'blocked', screened: { forward: null, answers, batch } };
+    }
+    const target = ready(session, signal);
+    const upstream = await forward(target, pending, signal);
+    if (upstream.status !== 401 && upstream.status !== 403) return { kind: 'response', upstream, answers };
+    await upstream.body?.cancel();
+  }
+  throw new ApiError('The organization connector rejected its credential. Check its sign-in in the organization settings.', 424);
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/org-runtime-discovery.ts

@@ -0,0 +1,115 @@
+import type { FetchLike } from '@metro-labs/core/stations/oauth';
+import type { ToolGroup } from '@metro-labs/core/stations/types';
+import { ApiError } from '@metro-labs/http/api-error';
+import { validConnectorToolName, type DeliveredConnector } from '@metro-labs/http/connector-delivery';
+import { MetroApiRefusal } from './metro-api.js';
+import { listRemoteTools } from './tools.js';
+
+export const orgUnavailable = (): ApiError => new ApiError('This organization connector is not available. Try again.', 503);
+export const orgSignin = (): ApiError => new ApiError('This organization connector needs sign-in again.', 424);
+export const orgMissing = (): ApiError => new ApiError('No such organization connector is assigned to this agent.', 404);
+
+export function orgRuntimeError(error: unknown): ApiError {
+  if (error instanceof MetroApiRefusal) return error.upstreamStatus === 401 || error.upstreamStatus === 403 ? orgSignin() : orgUnavailable();
+  const status = error instanceof ApiError ? error.status : 503;
+  if (status === 401 || status === 403 || status === 424) return orgSignin();
+  if (status === 404) return orgMissing();
+  if (status === 502) return new ApiError('The organization connector could not complete the request.', 502);
+  return orgUnavailable();
+}
+
+interface DiscoveryGuard {
+  fresh: (revision?: string) => Promise<DeliveredConnector>;
+  current: () => DeliveredConnector;
+  signal: AbortSignal;
+  fetch: FetchLike;
+}
+
+const MAX_BYTES = 2 * 1024 * 1024;
+const MAX_TOOLS = 2000;
+
+async function boundedResponse(response: Response, signal: AbortSignal): Promise<Response> {
+  const reader = response.body?.getReader();
+  if (reader === undefined) return response;
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    for (let part = await reader.read(); !part.done; part = await reader.read()) {
+      signal.throwIfAborted();
+      size += part.value.length;
+      if (size > MAX_BYTES) throw orgUnavailable();
+      chunks.push(part.value);
+    }
+    return new Response(Buffer.concat(chunks), { status: response.status, headers: response.headers });
+  } finally {
+    await reader.cancel();
+  }
+}
+
+function requestInit(row: DeliveredConnector, init: RequestInit | undefined, scanSignal: AbortSignal): RequestInit & { signal: AbortSignal } {
+  const headers = new Headers(init?.headers);
+  for (const [name, value] of Object.entries(row.headers)) headers.set(name, value);
+  const signals = [scanSignal, AbortSignal.timeout(15_000)];
+  if (init?.signal !== undefined && init.signal !== null) signals.push(init.signal);
+  return { ...init, headers, redirect: 'manual', signal: AbortSignal.any(signals) };
+}
+
+async function discoveryResponse(response: Response, init: RequestInit | undefined, signal: AbortSignal): Promise<Response> {
+  if (response.status >= 300) throw new ApiError('The organization connector refused tool discovery.', 502);
+  if (init?.method === 'DELETE') {
+    await boundedResponse(response, signal);
+    return new Response(null, { status: response.status });
+  }
+  return boundedResponse(response, signal);
+}
+
+async function guardedRequest(input: string, init: RequestInit | undefined, guard: DiscoveryGuard, budget: { refreshed: boolean }): Promise<Response> {
+  let revision: string | undefined;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    guard.signal.throwIfAborted();
+    await guard.fresh(revision);
+    guard.signal.throwIfAborted();
+    const row = guard.current();
+    if (input !== new URL(row.url).toString()) throw orgUnavailable();
+    const options = requestInit(row, init, guard.signal);
+    const response = await guard.fetch(input, options);
+    try {
+      guard.current();
+      options.signal.throwIfAborted();
+      if (response.status === 401 || response.status === 403) {
+        if (row.auth !== 'oauth' || budget.refreshed) throw orgSignin();
+        budget.refreshed = true;
+        revision = row.revision;
+        continue;
+      }
+      return await discoveryResponse(response, init, options.signal);
+    } finally {
+      if (!response.bodyUsed) await response.body?.cancel();
+    }
+  }
+  throw orgSignin();
+}
+
+export async function discoverOrgGroups(url: string, guard: DiscoveryGuard): Promise<Record<string, ToolGroup>> {
+  try {
+    const failure: { error: ApiError | null } = { error: null };
+    const budget = { refreshed: false };
+    const send: FetchLike = async (input, init) => {
+      try {
+        return await guardedRequest(input, init, guard, budget);
+      } catch (error) {
+        const safe = orgRuntimeError(error);
+        if (init?.method !== 'DELETE' || safe.status !== 502) failure.error = safe;
+        throw safe;
+      }
+    };
+    const tools = await listRemoteTools(new URL(url), { kind: 'none' }, send);
+    if (failure.error !== null) throw failure.error;
+    guard.current();
+    guard.signal.throwIfAborted();
+    if (tools.length > MAX_TOOLS || tools.some((tool) => !validConnectorToolName(tool.name))) throw orgUnavailable();
+    return Object.fromEntries(tools.map((tool) => [tool.name, tool.readOnly ? 'read' : 'write']));
+  } catch (error) {
+    throw orgRuntimeError(error);
+  }
+}