@stage-labs/metro 0.1.0-beta.21 → 0.1.0-beta.210

package/runtime/node_modules/@metro-labs/{mcp/src/daemon → daemon/src/connectors}/oauth-client.ts

@@ -1,9 +1,8 @@
 import { createHash, randomBytes } from 'node:crypto';
-import {
-  ConnectorVerifyError,
-  type OAuthTokens,
-} from './connector-verify.js';
+import { whyUnreachable } from './reach.js';
+import { refused, type OAuthTokens } from './verify.js';
 import type { OAuthServer } from './oauth-discovery.js';
+import { isRecord } from '@metro-labs/core/is-record';
 
 const TOKEN_TIMEOUT_MS = 15_000;
 const CLIENT_NAME = 'Metro';
@@ -13,14 +12,6 @@ export interface OAuthClient {
   clientSecret?: string;
 }
 
-function refused(message: string): ConnectorVerifyError {
-  return new ConnectorVerifyError(message, 400);
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 export function newVerifier(): string {
   return randomBytes(32).toString('base64url');
 }
@@ -35,7 +26,9 @@ export async function registerClient(
 ): Promise<OAuthClient> {
   if (server.registrationEndpoint === null)
     throw refused(
-      'That server requires OAuth but does not accept client registration, so Metro cannot sign in to it.',
+      'That server signs in with OAuth but registers no clients on its own. ' +
+        `Register an app with it yourself, with ${redirectUri} as its redirect URL, ` +
+        "and add the connector again with that app's client ID.",
     );
   let res: Response;
   try {
@@ -52,8 +45,8 @@ export async function registerClient(
         token_endpoint_auth_method: 'none',
       }),
     });
-  } catch {
-    throw refused('Metro could not reach that server to register.');
+  } catch (err) {
+    throw refused(`Metro could not reach that server to register: ${whyUnreachable(err)}`);
   }
   const body: unknown = await res.json().catch(() => null);
   if (!res.ok || !isRecord(body) || typeof body.client_id !== 'string')
@@ -83,6 +76,8 @@ export function authorizeUrl(input: AuthorizeInput): string {
   url.searchParams.set('code_challenge', challengeOf(input.verifier));
   url.searchParams.set('code_challenge_method', 'S256');
   url.searchParams.set('resource', input.resource);
+  if (input.server.scopes.length > 0)
+    url.searchParams.set('scope', input.server.scopes.join(' '));
   return url.toString();
 }
 
@@ -125,8 +120,8 @@ async function postToken(
       },
       body: params.toString(),
     });
-  } catch {
-    throw refused('Metro could not reach that server to finish signing in.');
+  } catch (err) {
+    throw refused(`Metro could not reach that server to finish signing in: ${whyUnreachable(err)}`);
   }
   const body: unknown = await res.json().catch(() => null);
   if (!res.ok || !isRecord(body))
@@ -153,10 +148,12 @@ export function refreshTokens(
   client: OAuthClient,
   refreshToken: string,
   resource: string,
+  scope?: string,
 ): Promise<OAuthTokens> {
   return postToken(server, client, {
     grant_type: 'refresh_token',
     refresh_token: refreshToken,
     resource,
+    ...(scope === undefined ? {} : { scope }),
   });
 }

package/runtime/node_modules/@metro-labs/{mcp/src/daemon → daemon/src/connectors}/oauth-discovery.ts

@@ -1,4 +1,6 @@
-import { ConnectorVerifyError, parseConnectorUrl } from './connector-verify.js';
+import { parseConnectorUrl, refused } from './verify.js';
+import { stringOf } from '@metro-labs/http/api-http';
+import { isRecord } from '@metro-labs/core/is-record';
 
 const DISCOVERY_TIMEOUT_MS = 10_000;
 
@@ -8,19 +10,14 @@ export interface OAuthServer {
   tokenEndpoint: string;
   registrationEndpoint: string | null;
   supportsS256: boolean;
+  scopes: string[];
 }
 
-function refused(message: string): ConnectorVerifyError {
-  return new ConnectorVerifyError(message, 400);
+interface ResourceMetadata {
+  issuer: URL;
+  scopes: string[];
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-const str = (value: unknown): string =>
-  typeof value === 'string' ? value : '';
-
 async function getJson(url: URL): Promise<Record<string, unknown> | null> {
   let res: Response;
   try {
@@ -68,32 +65,48 @@ export async function advertisesOAuth(resource: URL): Promise<boolean> {
   return false;
 }
 
-async function authServerFor(resource: URL): Promise<URL> {
+function scopesOf(body: Record<string, unknown> | null): string[] {
+  const raw: unknown = body?.scopes_supported;
+  if (!Array.isArray(raw)) return [];
+  const out: string[] = [];
+  for (const entry of raw) {
+    const scope = stringOf(entry).trim();
+    if (scope !== '' && !/\s/.test(scope) && !out.includes(scope)) out.push(scope);
+  }
+  return out;
+}
+
+async function resourceMetadata(resource: URL): Promise<ResourceMetadata> {
   for (const candidate of resourceMetadataUrls(resource)) {
     const body = await getJson(candidate);
     const servers: unknown = body?.authorization_servers;
     const first: unknown = Array.isArray(servers) ? servers[0] : undefined;
     if (typeof first === 'string' && first !== '')
-      return parseConnectorUrl(first);
+      return { issuer: parseConnectorUrl(first), scopes: scopesOf(body) };
   }
-  return parseConnectorUrl(resource.origin);
+  return { issuer: parseConnectorUrl(resource.origin), scopes: [] };
 }
 
-function toServer(body: Record<string, unknown>, issuer: URL): OAuthServer {
-  const authorizationEndpoint = str(body.authorization_endpoint);
-  const tokenEndpoint = str(body.token_endpoint);
+function toServer(
+  body: Record<string, unknown>,
+  issuer: URL,
+  scopes: string[],
+): OAuthServer {
+  const authorizationEndpoint = stringOf(body.authorization_endpoint);
+  const tokenEndpoint = stringOf(body.token_endpoint);
   if (authorizationEndpoint === '' || tokenEndpoint === '')
     throw refused(
       `${issuer.hostname} advertises OAuth but not where to sign in.`,
     );
   const methods = body.code_challenge_methods_supported;
-  const registration = str(body.registration_endpoint);
+  const registration = stringOf(body.registration_endpoint);
   return {
-    issuer: str(body.issuer) === '' ? issuer.origin : str(body.issuer),
+    issuer: stringOf(body.issuer) === '' ? issuer.origin : stringOf(body.issuer),
     authorizationEndpoint,
     tokenEndpoint,
     registrationEndpoint: registration === '' ? null : registration,
     supportsS256: Array.isArray(methods) ? methods.includes('S256') : false,
+    scopes,
   };
 }
 
@@ -109,10 +122,10 @@ export function authServerMetadataUrls(issuer: URL): URL[] {
 }
 
 export async function discoverOAuth(resource: URL): Promise<OAuthServer> {
-  const issuer = await authServerFor(resource);
+  const { issuer, scopes } = await resourceMetadata(resource);
   for (const candidate of authServerMetadataUrls(issuer)) {
     const body = await getJson(candidate);
-    if (body !== null) return toServer(body, issuer);
+    if (body !== null) return toServer(body, issuer, scopes);
   }
   throw refused(
     `${resource.hostname} needs authorization, but publishes no OAuth metadata Metro can use.`,

package/runtime/node_modules/@metro-labs/{mcp/src/daemon/connector-oauth-routes.ts → daemon/src/connectors/oauth-routes.ts}

@@ -1,18 +1,17 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import { errMsg, log } from './log.js';
-import { bodyField, readJsonBody, sendJson, type ApiSession } from './api-http.js';
+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 './connector-oauth.js';
-import { parseConnectorUrl } from './connector-verify.js';
-import type { OAuthAuth } from './connector-verify.js';
-import type { Connector } from '../db/connectors.js';
-
-const asText = (value: unknown): string =>
-  typeof value === 'string' ? value : '';
+} from './oauth.js';
+import { connectorClient } from './config.js';
+import { parseConnectorUrl } from './verify.js';
+import type { OAuthAuth } from './verify.js';
+import type { Connector, PendingConnectorInput } from './store.js';
 
 export function hostOf(url: string): string {
   try {
@@ -23,38 +22,37 @@ export function hostOf(url: string): string {
 }
 
 export interface OAuthRouteDeps {
-  createPendingConnector: (
-    email: string,
-    project: string,
-    input: { name: unknown; url: unknown },
-  ) => Promise<Connector>;
-  reconnectConnector: (
-    email: string,
-    id: string,
-    auth: OAuthAuth,
-  ) => Promise<Connector>;
-  getConnector: (email: string, id: string) => Promise<Connector>;
+  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,
-  session: ApiSession,
-  project: string,
   body: unknown,
   payload: (row: Connector) => Record<string, unknown>,
 ): Promise<void> {
   const url = parseConnectorUrl(bodyField(body, 'url'));
-  const row = await deps.createPendingConnector(session.email, project, {
+  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,
+  });
+  const row = await deps.createPendingConnector({
     name: bodyField(body, 'name'),
     url: bodyField(body, 'url'),
+    clientId,
+    clientSecret,
   });
-  const authorize = await beginOAuth({
-    email: session.email,
+  const authorize = beginOAuth(prepared, {
     name: row.name,
     url,
-    returnTo: asText(bodyField(body, 'returnTo')),
+    returnTo,
     connectorId: row.id,
   });
   log.info(
@@ -68,17 +66,17 @@ export async function handleConnect(
   req: IncomingMessage,
   res: ServerResponse,
   deps: OAuthRouteDeps,
-  session: ApiSession,
   id: string,
 ): Promise<void> {
-  const row = await deps.getConnector(session.email, id);
+  const row = await deps.getConnector(id);
   const url = parseConnectorUrl(row.url);
   const body = await readJsonBody(req);
-  const authorize = await beginOAuth({
-    email: session.email,
+  const returnTo = stringOf(bodyField(body, 'returnTo'));
+  const prepared = await prepareOAuth({ url, client: row.client, returnTo });
+  const authorize = beginOAuth(prepared, {
     name: row.name,
     url,
-    returnTo: asText(bodyField(body, 'returnTo')),
+    returnTo,
     connectorId: row.id,
   });
   log.info(
@@ -110,7 +108,7 @@ async function saveOAuth(
   entry: PendingAuth,
   auth: OAuthAuth,
 ): Promise<Connector> {
-  return deps.reconnectConnector(entry.email, entry.connectorId, auth);
+  return deps.reconnectConnector(entry.connectorId, auth);
 }
 
 async function settleCallback(

package/runtime/node_modules/@metro-labs/{mcp/src/daemon/connector-oauth.ts → daemon/src/connectors/oauth.ts}

@@ -1,53 +1,82 @@
-import { publicBaseOrDefault } from './attach-serve.js';
+import { publicBaseOrDefault } from '../files/attach-serve.js';
 import {
-  ConnectorVerifyError,
+  refused,
   type OAuthAuth,
   type OAuthTokens,
-} from './connector-verify.js';
-import { validateReturnTo } from './google-oauth.js';
+} from './verify.js';
+import { validateReturnTo } from '@metro-labs/http/return-to';
 import {
   authorizeUrl,
   exchangeCode,
   newVerifier,
   refreshTokens,
   registerClient,
+  type OAuthClient,
 } from './oauth-client.js';
-import { discoverOAuth } from './oauth-discovery.js';
-import { startPending, takePending, type PendingAuth } from './oauth-pending.js';
+import { discoverOAuth, type OAuthServer } from './oauth-discovery.js';
+import { ticketStore } from '@metro-labs/core/tickets';
 
-export { takePending, type PendingAuth };
+export interface PendingAuth {
+  name: string;
+  url: string;
+  resource: string;
+  returnTo: string;
+  verifier: string;
+  server: OAuthServer;
+  client: OAuthClient;
+  connectorId: string;
+}
 
-const REFRESH_SKEW_MS = 60_000;
+const pending = ticketStore<PendingAuth>(10 * 60_000, 100);
 
-export const CALLBACK_PATH = '/api/connectors/callback';
+export const startPending = (entry: PendingAuth, now = Date.now()): string => pending.mint(entry, now).ticket;
 
-export const callbackUri = (): string =>
-  `${publicBaseOrDefault()}${CALLBACK_PATH}`;
+export const takePending = (state: string, now = Date.now()): PendingAuth | undefined => pending.take(state, now);
 
-function refused(message: string): ConnectorVerifyError {
-  return new ConnectorVerifyError(message, 400);
-}
+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 BeginInput {
-  connectorId: string;
-  email: string;
-  name: string;
+export interface PrepareInput {
   url: URL;
+  client: OAuthClient | null;
   returnTo: string;
 }
 
-export async function beginOAuth(input: BeginInput): Promise<string> {
+export interface PreparedOAuth {
+  server: OAuthServer;
+  client: OAuthClient;
+  redirectUri: string;
+}
+
+export async function prepareOAuth(input: PrepareInput): 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);
   const redirectUri = callbackUri();
-  const client = await registerClient(server, redirectUri);
+  const client = input.client ?? (await registerClient(server, redirectUri));
+  return { server, client, redirectUri };
+}
+
+export interface BeginInput {
+  connectorId: string;
+  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({
-    email: input.email,
     name: input.name,
     url: input.url.toString(),
     resource,
@@ -76,6 +105,9 @@ function authOf(pendingAuth: PendingAuth, tokens: OAuthTokens): OAuthAuth {
     ...(pendingAuth.client.clientSecret === undefined
       ? {}
       : { clientSecret: pendingAuth.client.clientSecret }),
+    ...(pendingAuth.server.scopes.length === 0
+      ? {}
+      : { scope: pendingAuth.server.scopes.join(' ') }),
     ...tokens,
   };
 }
@@ -109,6 +141,7 @@ export async function refreshOAuth(
     tokenEndpoint: auth.tokenEndpoint,
     registrationEndpoint: null,
     supportsS256: true,
+    scopes: [],
   };
   const client = {
     clientId: auth.clientId,
@@ -116,7 +149,13 @@ export async function refreshOAuth(
       ? {}
       : { clientSecret: auth.clientSecret }),
   };
-  const tokens = await refreshTokens(server, client, auth.refreshToken, resource);
+  const tokens = await refreshTokens(
+    server,
+    client,
+    auth.refreshToken,
+    resource,
+    auth.scope,
+  );
   return {
     ...auth,
     ...tokens,

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

@@ -0,0 +1,131 @@
+import { existsSync, readdirEntries, readFileSync } from '../agent-user/agent-fs.js';
+import { writeHomeInPlace } from '../agent-user/home-fs.js';
+import { agentMarketplaceDir, agentUser } from '../agent-user/user.js';
+import { join } from 'node:path';
+import { errMsg, log } from '@metro-labs/core/log';
+import { claudeDir } from '../claude/files.js';
+import { loopbackBase } from '../files/attach-serve.js';
+
+const MARKER = join('bin', 'metro-plugin.mjs');
+const FILE = '.mcp.json';
+const HELPER = 'node "${CLAUDE_PLUGIN_ROOT}/bin/metro-plugin.mjs" headers';
+const SLUG_MAX = 40;
+
+export interface PluginRow {
+  id: string;
+  name: string;
+}
+
+export interface PluginServer {
+  type: 'http';
+  url: string;
+  headersHelper: string;
+}
+
+export function serverKey(name: string): string {
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, SLUG_MAX)
+    .replace(/-+$/, '');
+  return slug === '' ? 'connector' : slug;
+}
+
+export function serverKeysOf(rows: PluginRow[]): Map<string, string> {
+  const taken = new Map<string, number>();
+  const keys = new Map<string, string>();
+  for (const row of rows) {
+    const wanted = serverKey(row.name);
+    const seen = taken.get(wanted) ?? 0;
+    taken.set(wanted, seen + 1);
+    keys.set(row.id, seen === 0 ? wanted : `${wanted}-${row.id.toLowerCase().replace(/[^a-z0-9]/g, '').slice(0, 4)}`);
+  }
+  return keys;
+}
+
+export function pluginServers(rows: PluginRow[], base: string): Record<string, PluginServer> {
+  const out: Record<string, PluginServer> = {};
+  for (const [id, key] of serverKeysOf(rows)) out[key] = { type: 'http', url: `${base}/relay/${id}`, headersHelper: HELPER };
+  return out;
+}
+
+const SEARCH_DEPTH = 5;
+
+function pluginRootsUnder(dir: string, depth: number, out: string[]): void {
+  if (depth < 0 || out.length >= 8) return;
+  let entries;
+  try {
+    entries = readdirEntries(dir);
+  } catch {
+    return;
+  }
+  if (entries.some((e) => e.name === 'bin' && e.isDirectory()) && existsSync(join(dir, MARKER))) {
+    out.push(dir);
+    return;
+  }
+  for (const entry of entries)
+    if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules')
+      pluginRootsUnder(join(dir, entry.name), depth - 1, out);
+}
+
+function stagedPluginDir(env: NodeJS.ProcessEnv = process.env): string | null {
+  const store = env.METRO_RUNTIME_STORE?.trim() ?? '';
+  if (store === '') return null;
+  const user = agentUser();
+  return join(user === null ? join(store, 'marketplace') : agentMarketplaceDir(user), 'plugin');
+}
+
+export function installedPluginFiles(dir = claudeDir(), staged = stagedPluginDir()): string[] {
+  const roots: string[] = [];
+  const root = join(dir, 'plugins');
+  if (existsSync(root)) pluginRootsUnder(root, SEARCH_DEPTH, roots);
+  if (staged !== null && existsSync(join(staged, MARKER)) && !roots.includes(staged)) roots.push(staged);
+  return roots.map((found) => join(found, FILE));
+}
+
+const readOrNull = (path: string): string | null => {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+};
+
+function writeIfChanged(path: string, text: string): boolean {
+  if (readOrNull(path) === text) return false;
+  writeHomeInPlace(path, text, 0o644);
+  return true;
+}
+
+export interface PluginSyncOptions {
+  dir?: string;
+  base?: string;
+  staged?: string | null;
+}
+
+function filesFor(opts: PluginSyncOptions): string[] {
+  const staged = opts.staged === undefined ? stagedPluginDir() : opts.staged;
+  return installedPluginFiles(opts.dir ?? claudeDir(), staged);
+}
+
+export function syncPluginServers(rows: PluginRow[], opts: PluginSyncOptions = {}): number {
+  const files = filesFor(opts);
+  if (files.length === 0) return 0;
+  const servers = pluginServers(rows, opts.base ?? loopbackBase());
+  const text = `${JSON.stringify(servers, null, 2)}\n`;
+  let written = 0;
+  for (const file of files) {
+    try {
+      if (writeIfChanged(file, text)) written += 1;
+    } catch (err) {
+      log.warn({ file, err: errMsg(err) }, 'plugin: could not write the connector servers');
+    }
+  }
+  if (written > 0)
+    log.info(
+      { files: written, servers: Object.keys(servers).length },
+      'plugin: connector servers written; run /reload-plugins --force to pick them up in a running session',
+    );
+  return written;
+}

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

@@ -0,0 +1,27 @@
+import { errMsg } from '@metro-labs/core/log';
+
+const HINTS: Record<string, string> = {
+  ENOTFOUND: 'the name does not resolve',
+  EAI_AGAIN: 'the name did not resolve in time',
+  ECONNREFUSED: 'nothing is listening there',
+  ECONNRESET: 'the server dropped the connection',
+  ETIMEDOUT: 'the server did not answer in time',
+  ConnectionRefused: 'nothing is listening there',
+  CERT_HAS_EXPIRED: 'its certificate has expired',
+  DEPTH_ZERO_SELF_SIGNED_CERT: 'its certificate is self-signed',
+  UNABLE_TO_VERIFY_LEAF_SIGNATURE: 'its certificate could not be verified',
+  ERR_TLS_CERT_ALTNAME_INVALID: 'its certificate is for another name',
+  SELF_SIGNED_CERT_IN_CHAIN: 'its certificate chain is not trusted',
+};
+
+const codeOf = (err: unknown): string =>
+  err !== null && typeof err === 'object' && 'code' in err && typeof err.code === 'string' ? err.code : '';
+
+export function whyUnreachable(err: unknown): string {
+  const inner = err instanceof Error && err.cause instanceof Error ? err.cause : err;
+  const message = errMsg(inner).trim();
+  const code = codeOf(inner) || codeOf(err);
+  const said = message !== '' && message !== 'fetch failed' ? message : code || 'no answer';
+  const hint = HINTS[code];
+  return hint === undefined ? said : `${said} (${hint})`;
+}

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

@@ -0,0 +1,90 @@
+import type { ServerResponse } from 'node:http';
+import { isRecord } from '@metro-labs/core/is-record';
+import { log } from '@metro-labs/core/log';
+
+export type BlockedReason = (connectorId: string, tool: string, args: Record<string, unknown>) => string | null;
+
+export interface Screened {
+  forward: Uint8Array<ArrayBuffer> | null;
+  answers: Record<string, unknown>[];
+  batch: boolean;
+}
+
+const encoder = new TextEncoder();
+
+function parsed(body: Uint8Array): unknown {
+  try {
+    return JSON.parse(new TextDecoder().decode(body));
+  } catch {
+    return undefined;
+  }
+}
+
+function toolOf(message: unknown): string | null {
+  if (!isRecord(message) || message.method !== 'tools/call' || !isRecord(message.params)) return null;
+  const name = message.params.name;
+  return typeof name === 'string' ? name : null;
+}
+
+function blockedAnswer(message: Record<string, unknown>, reason: string): Record<string, unknown> | null {
+  if (!('id' in message)) return null;
+  return { jsonrpc: '2.0', id: message.id, result: { isError: true, content: [{ type: 'text', text: reason }] } };
+}
+
+function argsOf(message: unknown): Record<string, unknown> {
+  if (!isRecord(message) || !isRecord(message.params)) return {};
+  return isRecord(message.params.arguments) ? message.params.arguments : {};
+}
+
+function reasonFor(message: unknown, connectorId: string, blocked: BlockedReason): string | null {
+  const tool = toolOf(message);
+  return tool === null ? null : blocked(connectorId, tool, argsOf(message));
+}
+
+export function screenCalls(body: Uint8Array<ArrayBuffer>, connectorId: string, blocked: BlockedReason): Screened | null {
+  const message = parsed(body);
+  const batch = Array.isArray(message);
+  const list: unknown[] = batch ? message : [message];
+  const answers: Record<string, unknown>[] = [];
+  const kept: unknown[] = [];
+  for (const item of list) {
+    const reason = reasonFor(item, connectorId, blocked);
+    if (reason === null || !isRecord(item)) {
+      kept.push(item);
+      continue;
+    }
+    log.info({ connector: connectorId, tool: toolOf(item) }, 'relay: a call the owner blocked was answered without the connector');
+    const answer = blockedAnswer(item, reason);
+    if (answer !== null) answers.push(answer);
+  }
+  if (kept.length === list.length) return null;
+  const forward = kept.length === 0 ? null : new Uint8Array(encoder.encode(JSON.stringify(kept)));
+  return { forward, answers, batch };
+}
+
+export function answerBlocked(res: ServerResponse, screened: Screened): void {
+  if (res.headersSent) return;
+  if (screened.answers.length === 0) {
+    res.writeHead(202).end();
+    return;
+  }
+  const body = screened.batch ? screened.answers : screened.answers[0];
+  res.writeHead(200, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(body));
+}
+
+const sseFrames = (answers: Record<string, unknown>[]): string =>
+  answers.map((answer) => `event: message\ndata: ${JSON.stringify(answer)}\n\n`).join('');
+
+export async function mergeBlocked(res: ServerResponse, upstream: Response, headers: Record<string, string>, answers: Record<string, unknown>[]): Promise<void> {
+  const text = await upstream.text();
+  if ((headers['content-type'] ?? '').includes('text/event-stream')) {
+    res.writeHead(upstream.status, headers);
+    res.end(`${text}${sseFrames(answers)}`);
+    return;
+  }
+  const theirs = text.trim() === '' ? [] : parsed(encoder.encode(text));
+  const list: unknown[] = Array.isArray(theirs) ? theirs : theirs === undefined || theirs === null ? [] : [theirs];
+  res.writeHead(200, { ...headers, 'content-type': 'application/json' });
+  res.end(JSON.stringify([...list, ...answers]));
+}