@stage-labs/metro 0.1.0-beta.31 → 0.1.0-beta.310

package/runtime/node_modules/@metro-labs/http/src/connector-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/http/src/connector-resource.ts

@@ -0,0 +1,108 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import type { FetchLike } from '@metro-labs/core/stations/oauth';
+import { authServerMetadataUrls, resourceMetadataUrls, type OAuthServer } from './connector-discovery.js';
+import { boundOAuthResource, optionalOAuthResource, parsePublicConnectorUrl, publicOAuthResource } from './connector-public-url.js';
+import { refused, ConnectorVerifyError } from './connector-url.js';
+
+const METADATA_MAX = 1024 * 1024;
+const metadataError = (): Error => refused('The provider returned invalid or unavailable public OAuth metadata. Check its public OAuth resource and try again.');
+export class OAuthResourceRequired extends ConnectorVerifyError {
+  constructor() { super('Enter the provider’s public OAuth resource before continuing. It is shown in the sign-in page; never enter a private endpoint or credentials.', 400); }
+}
+
+async function metadataBody(res: Response): Promise<Record<string, unknown>> {
+  if (res.body === null) throw metadataError();
+  const reader = res.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.length;
+      if (size > METADATA_MAX) throw metadataError();
+      chunks.push(value);
+    }
+    const body: unknown = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    if (!isRecord(body)) throw metadataError();
+    return body;
+  } finally {
+    await reader.cancel().catch(() => undefined);
+  }
+}
+
+async function metadata(url: URL, send: FetchLike): Promise<Record<string, unknown> | null> {
+  try {
+    const res = await send(url.toString(), { redirect: 'manual', signal: AbortSignal.timeout(10_000), headers: { accept: 'application/json' } });
+    if (res.status === 404) {
+      await res.body?.cancel();
+      return null;
+    }
+    if (!res.ok) {
+      await res.body?.cancel();
+      throw metadataError();
+    }
+    return await metadataBody(res);
+  } catch {
+    throw metadataError();
+  }
+}
+
+function selectedResource(transport: URL, offered: string | undefined, body: Record<string, unknown> | null): string {
+  const advertised = body !== null && Object.hasOwn(body, 'resource') ? publicOAuthResource(body.resource) : undefined;
+  if (advertised !== undefined && offered !== undefined && advertised !== offered) throw metadataError();
+  const resource = advertised ?? offered;
+  if (resource === undefined) throw new OAuthResourceRequired();
+  return boundOAuthResource(transport.toString(), resource);
+}
+
+function issuerOf(body: Record<string, unknown> | null, transport: URL): string {
+  if (body === null || !Object.hasOwn(body, 'authorization_servers')) return transport.origin;
+  const servers = body.authorization_servers;
+  if (!Array.isArray(servers) || servers.length === 0 || servers.length > 20) throw metadataError();
+  const values = servers.map((value: unknown) => publicOAuthResource(value));
+  return values[0] ?? '';
+}
+
+function scopesOf(body: Record<string, unknown> | null): string[] {
+  if (body === null || !Object.hasOwn(body, 'scopes_supported')) return [];
+  const scopes = body.scopes_supported;
+  if (!Array.isArray(scopes) || scopes.length > 100 || scopes.some((scope: unknown) => typeof scope !== 'string' || !/^[\x21\x23-\x5b\x5d-\x7e]{1,128}$/.test(scope))) throw metadataError();
+  return [...new Set(scopes as string[])];
+}
+
+function serverOf(body: Record<string, unknown>, issuer: string, scopes: string[]): OAuthServer {
+  if (typeof body.issuer !== 'string' || publicOAuthResource(body.issuer) !== issuer) throw metadataError();
+  const endpoint = (raw: unknown): string => parsePublicConnectorUrl(raw).toString();
+  return {
+    issuer,
+    authorizationEndpoint: endpoint(body.authorization_endpoint),
+    tokenEndpoint: endpoint(body.token_endpoint),
+    registrationEndpoint: body.registration_endpoint === undefined ? null : endpoint(body.registration_endpoint),
+    supportsS256: Array.isArray(body.code_challenge_methods_supported) && body.code_challenge_methods_supported.includes('S256'),
+    scopes,
+  };
+}
+
+async function protectedMetadata(base: URL, send: FetchLike): Promise<Record<string, unknown> | null> {
+  for (const candidate of resourceMetadataUrls(base)) {
+    const body = await metadata(candidate, send);
+    if (body !== null) return body;
+  }
+  return null;
+}
+
+export async function discoverPublicOAuth(target: string, offered: unknown, send: FetchLike = fetch): Promise<{ server: OAuthServer; resource: string }> {
+  const transport = parsePublicConnectorUrl(target);
+  const explicit = optionalOAuthResource(offered);
+  if (explicit !== undefined) boundOAuthResource(target, explicit);
+  const body = await protectedMetadata(new URL(explicit ?? transport.origin), send);
+  const resource = selectedResource(transport, explicit, body);
+  const issuer = issuerOf(body, transport);
+  const scopes = scopesOf(body);
+  for (const candidate of authServerMetadataUrls(new URL(issuer))) {
+    const authorization = await metadata(candidate, send);
+    if (authorization !== null) return { server: serverOf(authorization, issuer, scopes), resource };
+  }
+  throw metadataError();
+}

package/runtime/node_modules/@metro-labs/http/src/connector-tools.ts

@@ -0,0 +1,95 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg, log } from '@metro-labs/core/log';
+import type { FetchLike } from '@metro-labs/core/stations/oauth';
+import { authHeaders, INITIALIZE, mcpPost, payloadOf, type ConnectorAuth } from './connector-mcp.js';
+import { ConnectorUnauthorized, refused } from './connector-url.js';
+
+export interface RemoteTool {
+  name: string;
+  title: string;
+  description: string;
+  readOnly: boolean;
+  inputSchema?: Record<string, unknown>;
+}
+
+const TIMEOUT_MS = 15_000;
+const MAX_PAGES = 100;
+const MAX_TOOLS = 2000;
+
+function resultOf(text: string, contentType: string): Record<string, unknown> | null {
+  let parsed: unknown = null;
+  try {
+    parsed = JSON.parse(payloadOf(text, contentType));
+  } catch {
+    return null;
+  }
+  return isRecord(parsed) && isRecord(parsed.result) ? parsed.result : null;
+}
+
+async function rpc(url: URL, auth: ConnectorAuth, session: Map<string, string>, body: unknown, fetchImpl?: FetchLike): Promise<Record<string, unknown> | null> {
+  const res = await mcpPost(url, auth, body, { timeoutMs: TIMEOUT_MS, headers: Object.fromEntries(session), fetch: fetchImpl });
+  const id = res.headers.get('mcp-session-id');
+  if (id !== null && id !== '') session.set('mcp-session-id', id);
+  const text = await res.text().catch(() => '');
+  if (res.status === 401 || res.status === 403) throw new ConnectorUnauthorized(`${url.hostname} rejected the credential; connect it again`, 400);
+  if (!res.ok) throw refused(`${url.hostname} answered ${String(res.status)}`);
+  return resultOf(text, res.headers.get('content-type') ?? '');
+}
+
+function toTool(raw: unknown): RemoteTool | null {
+  if (!isRecord(raw) || typeof raw.name !== 'string') return null;
+  const annotations = isRecord(raw.annotations) ? raw.annotations : {};
+  const title = typeof raw.title === 'string' && raw.title !== '' ? raw.title : raw.name;
+  return { name: raw.name, title, description: typeof raw.description === 'string' ? raw.description : '', readOnly: annotations.readOnlyHint === true, ...(isRecord(raw.inputSchema) ? { inputSchema: raw.inputSchema } : {}) };
+}
+
+async function endSession(url: URL, auth: ConnectorAuth, session: Map<string, string>, fetchImpl?: FetchLike): Promise<void> {
+  if (!session.has('mcp-session-id')) return;
+  try {
+    const send = fetchImpl ?? fetch;
+    const res = await send(url.toString(), { method: 'DELETE', redirect: 'manual', signal: AbortSignal.timeout(TIMEOUT_MS), headers: { ...authHeaders(auth), ...Object.fromEntries(session) } });
+    if (res.ok) await res.body?.pipeTo(new WritableStream<Uint8Array>());
+    else await res.body?.cancel();
+  } catch (err) {
+    log.debug(fetchImpl === undefined ? { host: url.hostname, err: errMsg(err) } : {}, 'connector-tools: the remote declined to end the session');
+  }
+}
+
+function addTools(result: Record<string, unknown> | null, tools: Map<string, RemoteTool>): unknown {
+  if (result === null || !Array.isArray(result.tools)) throw refused('The provider did not return a complete tool list.');
+  for (const raw of result.tools) {
+    const tool = toTool(raw);
+    if (tool === null || tools.has(tool.name)) throw refused('The provider returned an invalid tool list.');
+    tools.set(tool.name, tool);
+    if (tools.size > MAX_TOOLS) throw refused('The provider returned too many tools.');
+  }
+  return result.nextCursor;
+}
+
+async function walkTools(url: URL, auth: ConnectorAuth, session: Map<string, string>, fetchImpl?: FetchLike): Promise<RemoteTool[]> {
+  const tools = new Map<string, RemoteTool>();
+  const cursors = new Set<string>();
+  let cursor = '';
+  for (let page = 0; page < MAX_PAGES; page += 1) {
+    const result = await rpc(url, auth, session, { jsonrpc: '2.0', id: 2 + page, method: 'tools/list', params: cursor === '' ? {} : { cursor } }, fetchImpl);
+    const next = addTools(result, tools);
+    if (next === undefined || next === null || next === '') return [...tools.values()];
+    if (typeof next !== 'string' || cursors.has(next)) throw refused('The provider did not return a complete tool list.');
+    cursors.add(next);
+    cursor = next;
+  }
+  throw refused('The provider did not return a complete tool list.');
+}
+
+export async function listRemoteTools(url: URL, auth: ConnectorAuth, fetchImpl?: FetchLike): Promise<RemoteTool[]> {
+  const session = new Map<string, string>();
+  try {
+    const init = await rpc(url, auth, session, INITIALIZE, fetchImpl);
+    if (init === null || typeof init.protocolVersion !== 'string') throw refused(`${url.hostname} answered, but it does not speak MCP.`);
+    session.set('mcp-protocol-version', init.protocolVersion);
+    await rpc(url, auth, session, { jsonrpc: '2.0', method: 'notifications/initialized' }, fetchImpl);
+    return await walkTools(url, auth, session, fetchImpl);
+  } finally {
+    await endSession(url, auth, session, fetchImpl);
+  }
+}

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

@@ -4,22 +4,17 @@ export class ConnectorVerifyError extends ApiError {}
 
 export class ConnectorUnauthorized extends ConnectorVerifyError {}
 
-export class ConnectorNotMcp extends ConnectorVerifyError {}
-
-export const POLICY_MESSAGE =
-  'Metro connects from its own server, so it cannot reach a URL on your machine. localhost and private addresses are not usable as connectors.';
-
-const IPV4 = /^\d{1,3}(?:\.\d{1,3}){3}$/;
-const PRIVATE_SUFFIX = /(?:^|\.)(?:localhost|local|internal|flycast)$/;
-
 export function refused(message: string): ConnectorVerifyError {
   return new ConnectorVerifyError(message, 400);
 }
 
-function hostAllowed(host: string): boolean {
-  if (host === '' || host.startsWith('[')) return false;
-  if (IPV4.test(host) || !host.includes('.')) return false;
-  return !PRIVATE_SUFFIX.test(host);
+function refuseShape(url: URL): void {
+  if (url.protocol !== 'https:' && url.protocol !== 'http:')
+    throw refused('a connector url must start with https:// or http://');
+  if (url.username !== '' || url.password !== '')
+    throw refused('a connector url must not carry a user:password');
+  if (url.hash !== '')
+    throw refused('a connector url must not carry a #fragment');
 }
 
 export function parseConnectorUrl(raw: unknown): URL {
@@ -31,13 +26,7 @@ export function parseConnectorUrl(raw: unknown): URL {
   } catch {
     throw refused('that is not a valid url');
   }
-  if (url.protocol !== 'https:')
-    throw refused('a connector url must start with https://');
-  if (url.username !== '' || url.password !== '')
-    throw refused('a connector url must not carry a user:password');
-  if (url.hash !== '')
-    throw refused('a connector url must not carry a #fragment');
-  if (!hostAllowed(url.hostname.toLowerCase())) throw refused(POLICY_MESSAGE);
+  refuseShape(url);
   return url;
 }
 
@@ -46,12 +35,3 @@ export function connectorUrlText(url: URL): string {
   if (url.pathname !== '/' || url.search !== '') return text;
   return text.endsWith('/') ? text.slice(0, -1) : text;
 }
-
-export function safeIconSrc(raw: unknown): string {
-  if (typeof raw !== 'string' || raw === '') return '';
-  try {
-    return new URL(raw).protocol === 'https:' ? raw.slice(0, 500) : '';
-  } catch {
-    return '';
-  }
-}

package/runtime/node_modules/@metro-labs/http/src/ed25519.ts

@@ -0,0 +1,56 @@
+const P = 2n ** 255n - 19n;
+
+interface Point {
+  x: bigint;
+  y: bigint;
+}
+
+const mod = (a: bigint): bigint => ((a % P) + P) % P;
+
+function pow(base: bigint, exp: bigint): bigint {
+  let result = 1n;
+  let b = mod(base);
+  for (let e = exp; e > 0n; e >>= 1n) {
+    if ((e & 1n) === 1n) result = (result * b) % P;
+    b = (b * b) % P;
+  }
+  return result;
+}
+
+const inv = (a: bigint): bigint => pow(a, P - 2n);
+const D = mod(-121665n * inv(121666n));
+const SQRT_M1 = pow(2n, (P - 1n) / 4n);
+
+function rootOf(u: bigint, v: bigint): bigint | null {
+  const x = mod(u * pow(v, 3n) * pow(mod(u * pow(v, 7n)), (P - 5n) / 8n));
+  const vx2 = mod(v * x * x);
+  if (vx2 === u) return x;
+  return vx2 === mod(-u) ? mod(x * SQRT_M1) : null;
+}
+
+function decode(bytes: Buffer): Point | null {
+  if (bytes.length !== 32) return null;
+  const last = bytes[31] ?? 0;
+  const sign = BigInt(last >> 7);
+  const copy = Buffer.from(bytes);
+  copy[31] = last & 0x7f;
+  const y = BigInt(`0x${copy.reverse().toString('hex')}`);
+  if (y >= P) return null;
+  const y2 = (y * y) % P;
+  const x = rootOf(mod(y2 - 1n), mod(D * y2 + 1n));
+  if (x === null || (x === 0n && sign === 1n)) return null;
+  return { x: (x & 1n) === sign ? x : mod(-x), y };
+}
+
+function add(a: Point, b: Point): Point {
+  const t = mod(D * a.x * b.x * a.y * b.y);
+  return { x: mod((a.x * b.y + a.y * b.x) * inv(mod(1n + t))), y: mod((a.y * b.y + a.x * b.x) * inv(mod(1n - t))) };
+}
+
+export function strongEd25519(raw: Buffer): boolean {
+  const point = decode(raw);
+  if (point === null) return false;
+  let eight = point;
+  for (let i = 0; i < 3; i += 1) eight = add(eight, eight);
+  return !(eight.x === 0n && eight.y === 1n);
+}

package/runtime/node_modules/@metro-labs/http/src/mcp-server-protocol.ts

@@ -0,0 +1,86 @@
+import { isRecord } from '@metro-labs/core/is-record';
+
+export const MCP_PATHS = { token: '/v1/token', approvals: '/v1/approvals', answer: '/v1/approvals/answer' } as const;
+export const MCP_FIND_DEFAULT = 5;
+export const MCP_FIND_MAX = 20;
+export const MCP_CALLS_MAX = 10;
+export const MCP_QUERY_MAX = 500;
+export const MCP_APPROVAL_WAIT_MS = 25_000;
+export const MCP_APPROVAL_ID_RE = /^[a-km-z]{5}$/;
+export const TOOL_SEARCH = 'tool_search';
+export const TOOL_CALL = 'tool_call';
+export const TOOL_CALL_EXAMPLE = '{"calls":[{"tool":"notion.search","arguments":{"query":"roadmap"}}]}';
+
+const EXPECTED = ` Expected: ${TOOL_CALL_EXAMPLE}, with names as tool_search returns them.`;
+export const MCP_TOKEN_RE = /^mcp_[A-Za-z0-9_-]{43}$/;
+
+export type McpErrorCode = 'blocked' | 'needs_approval' | 'denied' | 'not_found' | 'signin' | 'unavailable' | 'vendor_error' | 'invalid';
+
+export interface McpFindRequest {
+  query: string;
+  max_results: number;
+}
+
+export interface McpCall {
+  tool: string;
+  arguments: Record<string, unknown>;
+  approval?: string;
+}
+
+export interface McpApproval {
+  id: string;
+  connector: string;
+  tool: string;
+  preview: string;
+  requestedAt: number;
+}
+
+export type McpDecision = 'allow' | 'deny';
+
+const TOOL_RE = /^([a-z0-9][a-z0-9-]{0,62})\.([A-Za-z0-9_][A-Za-z0-9_.:/-]{0,127})$/;
+
+export function splitMcpTool(name: string): { connector: string; tool: string } | null {
+  const match = TOOL_RE.exec(name);
+  return match === null ? null : { connector: match[1] ?? '', tool: match[2] ?? '' };
+}
+
+export function mcpFindRequestOf(raw: unknown): McpFindRequest {
+  if (!isRecord(raw) || typeof raw.query !== 'string' || raw.query.trim() === '' || raw.query.length > MCP_QUERY_MAX) throw new Error('tool_search needs a query of 1 to 500 characters.');
+  const wanted = raw.max_results ?? MCP_FIND_DEFAULT;
+  if (typeof wanted !== 'number' || !Number.isInteger(wanted) || wanted < 1) throw new Error('max_results must be a whole number from 1.');
+  return { query: raw.query.trim(), max_results: Math.min(wanted, MCP_FIND_MAX) };
+}
+
+function callOf(raw: unknown): McpCall {
+  if (!isRecord(raw) || typeof raw.tool !== 'string' || splitMcpTool(raw.tool) === null) throw new Error(`Each call needs a tool named <connector>.<tool>, as tool_search returns it.${EXPECTED}`);
+  const args = raw.arguments ?? {};
+  if (!isRecord(args)) throw new Error(`The arguments of ${raw.tool} must be an object.${EXPECTED}`);
+  if (raw.approval !== undefined && (typeof raw.approval !== 'string' || !MCP_APPROVAL_ID_RE.test(raw.approval))) throw new Error('approval must be the 5-letter id the approval request gave.');
+  return { tool: raw.tool, arguments: args, ...(typeof raw.approval === 'string' ? { approval: raw.approval } : {}) };
+}
+
+export function mcpCallsOf(raw: unknown): McpCall[] {
+  const calls = isRecord(raw) ? raw.calls : undefined;
+  if (!Array.isArray(calls) || calls.length === 0 || calls.length > MCP_CALLS_MAX) throw new Error(`tool_call needs 1 to ${String(MCP_CALLS_MAX)} calls in "calls".${EXPECTED}`);
+  return calls.map(callOf);
+}
+
+export function mcpTokenHashOf(raw: unknown): string {
+  if (!isRecord(raw) || typeof raw.tokenHash !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(raw.tokenHash)) throw new Error('tokenHash must be the base64url SHA-256 of the MCP token.');
+  return raw.tokenHash;
+}
+
+function approvalOf(raw: unknown): McpApproval | null {
+  if (!isRecord(raw) || typeof raw.id !== 'string' || !MCP_APPROVAL_ID_RE.test(raw.id) || typeof raw.connector !== 'string' || typeof raw.tool !== 'string' || typeof raw.preview !== 'string' || typeof raw.requestedAt !== 'number') return null;
+  return { id: raw.id, connector: raw.connector, tool: raw.tool, preview: raw.preview, requestedAt: raw.requestedAt };
+}
+
+export function mcpApprovalsOf(raw: unknown): McpApproval[] {
+  if (!isRecord(raw) || !Array.isArray(raw.approvals)) throw new Error('Mcp sent an unreadable approval list.');
+  return raw.approvals.map(approvalOf).filter((row): row is McpApproval => row !== null);
+}
+
+export function mcpAnswerOf(raw: unknown): { id: string; decision: McpDecision } {
+  if (!isRecord(raw) || typeof raw.id !== 'string' || !MCP_APPROVAL_ID_RE.test(raw.id) || (raw.decision !== 'allow' && raw.decision !== 'deny')) throw new Error('An answer needs the approval id and allow or deny.');
+  return { id: raw.id, decision: raw.decision };
+}

package/runtime/node_modules/@metro-labs/http/src/mcp-server-tools.ts

@@ -0,0 +1,93 @@
+import { MCP_CALLS_MAX, MCP_FIND_DEFAULT, MCP_FIND_MAX, TOOL_CALL, TOOL_CALL_EXAMPLE, TOOL_SEARCH } from './mcp-server-protocol.js';
+
+export interface McpServerTool {
+  name: string;
+  title: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  annotations: Record<string, unknown>;
+}
+
+const searchSchema = {
+  type: 'object',
+  properties: {
+    query: {
+      type: 'string',
+      description: 'What to look for: "select:<connector>.<tool>" (comma separated) loads exact tools, keywords rank tools, "+word" requires that word in the tool name.',
+    },
+    max_results: { type: 'number', description: `Maximum number of results to return (default: ${String(MCP_FIND_DEFAULT)}, at most ${String(MCP_FIND_MAX)})`, default: MCP_FIND_DEFAULT },
+  },
+  required: ['query'],
+  additionalProperties: false,
+};
+
+const callSchema = {
+  type: 'object',
+  properties: {
+    calls: {
+      type: 'array',
+      minItems: 1,
+      maxItems: MCP_CALLS_MAX,
+      description: `1 to ${String(MCP_CALLS_MAX)} independent calls. They run in parallel and are answered in order.`,
+      items: {
+        type: 'object',
+        properties: {
+          tool: { type: 'string', description: 'The tool name exactly as tool_search returned it: <connector>.<tool>.' },
+          arguments: { type: 'object', description: 'The tool\'s arguments, matching the parameters tool_search returned.', additionalProperties: true },
+          approval: { type: 'string', pattern: '^[a-km-z]{5}$', description: 'The 5-letter approval id, only when repeating a call the owner approved.' },
+        },
+        required: ['tool'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['calls'],
+  additionalProperties: false,
+};
+
+function connectorsLine(keys: string[] | null): string {
+  if (keys === null) return 'The connectors of this agent are named here once Metro reaches mcp.metro.box.';
+  return keys.length === 0 ? 'This agent has no connectors it may use yet.' : `This agent's connectors: ${keys.join(', ')}.`;
+}
+
+export const toolSearchDescription = (keys: string[] | null): string =>
+  [
+    'Search the tools of every connector assigned to this agent: third-party services such as Notion, n8n, Linear or Gmail, run by mcp.metro.box. Same design as Claude Code\'s ToolSearch, for connectors.',
+    connectorsLine(keys),
+    'Three query forms, one example each:',
+    '- "select:notion.search" loads exact tools by name (comma separated for several).',
+    '- "notion create page" ranks tools by the words in their name and description.',
+    '- "+linear issue" requires "linear" in the tool name and ranks by the other words.',
+    'Results are full definitions (name, description and the JSON schema of the arguments) in a <functions> block. Each name is <connector>.<tool>: pass it exactly as "tool" to tool_call. Tools the owner blocked are never returned.',
+  ].join('\n');
+
+export const TOOL_CALL_DESCRIPTION = [
+  'Run connector tools that tool_search found. Always find a tool with tool_search first: its exact name and argument schema come from there.',
+  `Shape: ${TOOL_CALL_EXAMPLE}`,
+  `Up to ${String(MCP_CALLS_MAX)} independent calls run in parallel in one tool_call and are answered in order. Each result starts with "[n] <connector>.<tool>", then the tool's own content, or one line saying why it did not run:`,
+  '- not_found: no such connector or tool here. Run tool_search, then use a name it returned.',
+  '- needs_approval: the owner was asked in chat and on metro.box. Tell the person what is waiting, wait for the channel message "Approved: <tool> (<id>)", then call again with the same tool and arguments plus "approval": "<id>". An approval works once.',
+  '- denied or blocked: the owner refused or blocked this call. Do not retry it.',
+  '- signin: the connector must be signed in again. Tell the owner to do it on the organization\'s Connectors page on metro.box.',
+  '- unavailable: the connector or Metro could not be reached. Try again later.',
+  '- vendor_error: the connector answered with its own error, shown as it came.',
+].join('\n');
+
+export function mcpServerTools(keys: string[] | null): McpServerTool[] {
+  return [
+    {
+      name: TOOL_SEARCH,
+      title: 'Search connector tools',
+      description: toolSearchDescription(keys),
+      inputSchema: searchSchema,
+      annotations: { title: 'Search connector tools', readOnlyHint: true, openWorldHint: false },
+    },
+    {
+      name: TOOL_CALL,
+      title: 'Call connector tools',
+      description: TOOL_CALL_DESCRIPTION,
+      inputSchema: callSchema,
+      annotations: { title: 'Call connector tools', readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    },
+  ];
+}

package/runtime/node_modules/@metro-labs/{mcp/src/daemon/session-api.ts → http/src/mode-api.ts}

@@ -1,11 +1,20 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import { apiSession, cors, sendJson } from './api-http.js';
+import { cors, sendJson } from './api-http.js';
 
-const PATH = '/api/session';
+const PATH = '/api/mode';
 
-export function handleSessionApiRequest(
+export type DaemonMode = 'hosted' | 'local';
+
+export interface ModeInfo {
+  mode: DaemonMode;
+  owner: string | null;
+  version: string;
+}
+
+export function handleModeRequest(
   req: IncomingMessage,
   res: ServerResponse,
+  info: () => ModeInfo,
 ): boolean {
   const path = (req.url ?? '').split('?')[0] ?? '';
   if (path !== PATH) return false;
@@ -17,11 +26,6 @@ export function handleSessionApiRequest(
     sendJson(req, res, 405, { error: 'method not allowed' });
     return true;
   }
-  const session = apiSession(req);
-  if (!session) {
-    sendJson(req, res, 401, { error: 'unauthorized' });
-    return true;
-  }
-  sendJson(req, res, 200, { email: session.email });
+  sendJson(req, res, 200, info());
   return true;
 }

package/runtime/node_modules/@metro-labs/http/src/return-to.ts

@@ -0,0 +1,25 @@
+const PREVIEW = /^([a-z0-9-]+--)?metro-ui\.netlify\.app$/;
+
+export function allowedWebHost(host: string): boolean {
+  if (host === 'metro.box' || host === 'localhost' || host === '127.0.0.1')
+    return true;
+  return PREVIEW.test(host);
+}
+
+export const APP_RETURN = 'metro://auth';
+
+export const isAppReturn = (returnTo: string): boolean => returnTo === APP_RETURN;
+
+export function validateReturnTo(returnTo: string): boolean {
+  let url: URL;
+  try {
+    url = new URL(returnTo);
+  } catch {
+    return false;
+  }
+  const host = url.hostname;
+  if (url.protocol === 'http:' && (host === 'localhost' || host === '127.0.0.1'))
+    return true;
+  if (url.protocol !== 'https:') return false;
+  return allowedWebHost(host);
+}