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

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

@@ -0,0 +1,208 @@
+import { randomBytes } from 'node:crypto';
+import { log } from '@metro-labs/core/log';
+import type { ConnectorSyncReceipt } from '@metro-labs/core/connector-sync';
+import { ApiError } from '@metro-labs/http/api-error';
+import { AGENT_CLOCK_SKEW_MS } from '@metro-labs/http/agent-signature';
+import { CONNECTOR_DELIVERY_LEASE_MS, CONNECTOR_DELIVERY_MAX_BYTES, openConnectorDelivery, type DeliveryContext, type DeliverySnapshot } from '@metro-labs/http/connector-delivery';
+import type { AgentKey } from './agent-key.js';
+import { agentCall, MetroApiRefusal, type MetroApi } from './metro-api.js';
+
+interface Identity {
+  key: AgentKey;
+  context: Omit<DeliveryContext, 'requestId'>;
+  token: string;
+}
+
+export interface OrgSyncDeps {
+  enabled: () => boolean;
+  owner: () => string | null;
+  key: () => AgentKey | null;
+  api: MetroApi;
+  monotonic?: () => number;
+}
+
+interface RefreshRequest {
+  connectorId: string;
+  revision: string;
+}
+
+const invalid = (): ApiError => new ApiError('Metro received an invalid or expired organization connector snapshot.', 503);
+
+function lease(snapshot: DeliverySnapshot, started: number, elapsed: number, now: number): number {
+  const duration = snapshot.expiresAt - snapshot.issuedAt;
+  if (duration <= 0 || duration > CONNECTOR_DELIVERY_LEASE_MS || snapshot.issuedAt > now + AGENT_CLOCK_SKEW_MS || snapshot.issuedAt < started - AGENT_CLOCK_SKEW_MS) throw invalid();
+  const expiries = snapshot.connectors.flatMap((row) => row.state === 'ready' && row.expiresAt !== undefined ? [row.expiresAt] : []);
+  const remaining = Math.min(duration, ...expiries.map((at) => at - snapshot.issuedAt)) - elapsed;
+  if (remaining <= 0) throw invalid();
+  return remaining;
+}
+
+export class OrgConnectorSync {
+  private snapshot: DeliverySnapshot | null = null;
+  private token: string | null = null;
+  private controller: AbortController | null = null;
+  private receiptToken: string | null = null;
+  private receipt: ConnectorSyncReceipt = { state: 'waiting', lastReceivedAt: null, leaseExpiresAt: null, counts: null };
+  private deadline = 0;
+  private wallDeadline = 0;
+  private generation = 0;
+  private running: Promise<void> | null = null;
+  private recovery: Promise<void> | null = null;
+  private expiry: ReturnType<typeof setTimeout> | null = null;
+  private readonly monotonic: () => number;
+  private readonly listeners = new Set<() => void>();
+
+  constructor(private readonly deps: OrgSyncDeps) {
+    this.monotonic = deps.monotonic ?? (() => performance.now());
+  }
+
+  onChange(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => { this.listeners.delete(listener); };
+  }
+
+  epoch(): number {
+    return this.generation;
+  }
+
+  private notify(): void {
+    for (const listener of [...this.listeners]) {
+      try {
+        listener();
+      } catch {
+        log.warn('organization connectors: a memory change listener failed');
+      }
+    }
+  }
+
+  private identity(): Identity | null {
+    if (!this.deps.enabled()) return null;
+    const owner = this.deps.owner();
+    const key = this.deps.key();
+    const enrollment = key?.enrollment;
+    if (owner === null || key === null || enrollment === null || enrollment === undefined || enrollment.organization !== owner) return null;
+    const context = { owner, agent: enrollment.server, keyId: key.keyId };
+    return { key, context, token: JSON.stringify([context, key.sealingKey]) };
+  }
+
+  private forget(): void {
+    this.snapshot = null;
+    this.deadline = 0;
+    this.wallDeadline = 0;
+    if (this.expiry !== null) clearTimeout(this.expiry);
+    this.expiry = null;
+  }
+
+  private refused = false;
+  private settled = false;
+
+  lapsed(): boolean {
+    return !this.refused && (!this.settled || this.receipt.state === 'expired' || this.receipt.state === 'unavailable');
+  }
+
+  invalidate(reason: 'waiting' | 'expired' | 'unavailable' = 'waiting'): void {
+    if (reason === 'waiting') this.settled = true;
+    this.generation += 1;
+    this.controller?.abort();
+    this.controller = null;
+    if (reason === 'waiting') {
+      this.receiptToken = null;
+      this.receipt = { state: reason, lastReceivedAt: null, leaseExpiresAt: null, counts: null };
+    } else this.receipt = { ...this.receipt, state: reason, counts: null };
+    this.token = null;
+    this.forget();
+    this.notify();
+  }
+
+  private validate(identity: Identity | null): void {
+    if (this.token === null) return;
+    if (identity === null || identity.token !== this.token) this.invalidate();
+    else if (this.snapshot !== null && (this.monotonic() >= this.deadline || this.deps.api.now() >= this.wallDeadline)) this.invalidate('expired');
+  }
+
+  read(): DeliverySnapshot | null {
+    if (this.token === null) return null;
+    try {
+      this.validate(this.identity());
+    } catch {
+      this.invalidate();
+      log.warn('organization connectors: memory could not be checked and was cleared');
+    }
+    return this.snapshot === null ? null : structuredClone(this.snapshot);
+  }
+
+  status(): ConnectorSyncReceipt {
+    this.read();
+    try {
+      if (this.receiptToken !== null && this.identity()?.token !== this.receiptToken) this.invalidate();
+    } catch {
+      this.invalidate();
+    }
+    return structuredClone(this.receipt);
+  }
+
+  async sync(refresh?: RefreshRequest): Promise<void> {
+    let identity: Identity | null;
+    try {
+      identity = this.identity();
+      this.validate(identity);
+    } catch (err) {
+      this.invalidate();
+      throw err;
+    }
+    if (identity === null) return;
+    if (this.running !== null) return refresh === undefined ? this.running : this.running.then(() => this.sync(refresh));
+    this.token = identity.token;
+    const generation = this.generation;
+    this.controller = new AbortController();
+    this.running = this.fetch(identity, refresh, generation, this.controller.signal).then(() => {
+      this.refused = false;
+    }, (err: unknown) => {
+      if (generation === this.generation) {
+        this.refused = err instanceof MetroApiRefusal && err.upstreamStatus < 500;
+        this.invalidate('unavailable');
+      }
+      throw err;
+    }).finally(() => { this.running = null; });
+    return this.running;
+  }
+
+  recover(): Promise<void> {
+    if (this.read() !== null) return Promise.resolve();
+    this.recovery ??= this.syncFresh().finally(() => { this.recovery = null; });
+    return this.recovery;
+  }
+
+  async syncFresh(refresh?: RefreshRequest): Promise<void> {
+    if (this.running !== null) {
+      await this.running.catch(() => {
+        log.debug('organization connectors: a previous sync failed before a fresh check');
+      });
+    }
+    return this.sync(refresh);
+  }
+
+  private async fetch(identity: Identity, refresh: RefreshRequest | undefined, generation: number, signal: AbortSignal): Promise<void> {
+    const requestId = randomBytes(32).toString('base64url');
+    const context = { ...identity.context, requestId };
+    const started = this.deps.api.now();
+    const clock = this.monotonic();
+    const response = await agentCall(this.deps.api, identity.key, '/api/agents/connectors?policy_layers=1', { requestId, ...(refresh === undefined ? {} : { refresh }) }, { answerMax: CONNECTOR_DELIVERY_MAX_BYTES, timeoutMs: 60_000, signal });
+    this.validate(this.identity());
+    if (generation !== this.generation || this.token !== identity.token) throw invalid();
+    const snapshot = openConnectorDelivery(identity.key.sealing, context, response.sealed);
+    const remaining = lease(snapshot, started, this.monotonic() - clock, this.deps.api.now());
+    this.forget();
+    this.snapshot = snapshot;
+    this.deadline = this.monotonic() + remaining;
+    this.wallDeadline = this.deps.api.now() + remaining;
+    this.receiptToken = identity.token;
+    const total = snapshot.connectors.length;
+    const ready = snapshot.connectors.filter((row) => row.state === 'ready').length;
+    this.settled = true;
+    this.receipt = { state: 'received', lastReceivedAt: this.deps.api.now(), leaseExpiresAt: this.wallDeadline, counts: { total, ready, unavailable: total - ready } };
+    this.expiry = setTimeout(() => { this.invalidate('expired'); }, remaining);
+    this.expiry.unref();
+    this.notify();
+  }
+}

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

@@ -0,0 +1,170 @@
+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';
+import { isOrgRelayId } from './relay-id.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;
+}
+
+function legacyOwners(rows: PluginRow[], published: PluginRow[]): Map<string, string> {
+  const visible = new Set(published.map((row) => row.id));
+  const taken = new Map<string, number>();
+  const owners = new Map<string, string>();
+  const reserved = new Set<string>();
+  for (const row of rows.filter((entry) => !isOrgRelayId(entry.id))) {
+    const slug = serverKey(row.name);
+    const seen = taken.get(slug) ?? 0;
+    taken.set(slug, seen + 1);
+    const key = seen === 0 ? slug : `${slug}-${row.id.toLowerCase().replace(/[^a-z0-9]/g, '').slice(0, 4)}`;
+    reserved.add(key);
+    if (visible.has(row.id)) owners.set(key, row.id);
+  }
+  for (const row of rows.filter((entry) => isOrgRelayId(entry.id) && visible.has(entry.id)).sort((a, b) => a.id.localeCompare(b.id))) {
+    const key = availableKey(orgKey(row), reserved);
+    reserved.add(key);
+    owners.set(key, row.id);
+  }
+  return new Map([...owners].map(([key, id]) => [id, key]));
+}
+
+const orgKey = (row: PluginRow): string => `org-${serverKey(row.name).slice(0, 35)}-${Buffer.from(row.id.slice(4)).toString('hex')}`;
+
+function availableKey(wanted: string, reserved: ReadonlySet<string>): string {
+  let key = wanted;
+  let suffix = 1;
+  while (reserved.has(key)) key = `${wanted}-${String(suffix++)}`;
+  return key;
+}
+
+export function serverKeysOf(rows: PluginRow[], saved?: ReadonlyMap<string, string>, published: PluginRow[] = rows): Map<string, string> {
+  const keys = new Map(saved ?? legacyOwners(rows, published));
+  const reserved = new Set(keys.values());
+  const local = rows.filter((row) => !isOrgRelayId(row.id));
+  const organization = rows.filter((row) => isOrgRelayId(row.id)).sort((a, b) => a.id.localeCompare(b.id));
+  for (const row of [...local, ...organization]) {
+    if (keys.has(row.id)) continue;
+    const slug = serverKey(row.name);
+    const wanted = isOrgRelayId(row.id)
+      ? orgKey(row)
+      : reserved.has(slug) ? `${slug}-${row.id.toLowerCase().replace(/[^a-z0-9]/g, '').slice(0, 4)}` : slug;
+    const key = availableKey(wanted, reserved);
+    reserved.add(key);
+    keys.set(row.id, key);
+  }
+  return keys;
+}
+
+export function pluginServers(rows: PluginRow[], base: string, keys: ReadonlyMap<string, string> = serverKeysOf(rows)): Record<string, PluginServer> {
+  const out: Record<string, PluginServer> = {};
+  const visible = new Set(rows.map((row) => row.id));
+  for (const [id, key] of keys) if (visible.has(id)) 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;
+  keys?: ReadonlyMap<string, string>;
+}
+
+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(), opts.keys);
+  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/publication.ts

@@ -0,0 +1,61 @@
+import { registerConnectors, type GateRow } from './gates.js';
+import { syncPluginServers } from './plugin-sync.js';
+import { persistentServerKeys } from './server-keys.js';
+import { isOrgRelayId } from './relay-id.js';
+import { migrationRecords } from './migration-state.js';
+
+let local: GateRow[] = [];
+let organization: GateRow[] | null = null;
+
+function metadata(rows: readonly GateRow[]): GateRow[] {
+  return rows.map((row) => structuredClone({
+    id: row.id,
+    name: row.name,
+    config: {
+      ...(row.config.policy === undefined ? {} : { policy: row.config.policy }),
+      ...(row.config.toolGroups === undefined ? {} : { toolGroups: row.config.toolGroups }),
+    },
+  }));
+}
+
+function publishedRows(records: ReturnType<typeof migrationRecords>, organization: GateRow[]): GateRow[] {
+  const retired = new Set(records.filter((record) => !['preparing', 'prepared'].includes(record.phase)).map((record) => record.sourceId));
+  const aliases = new Map(organization.filter((row) => records.some((record) => record.phase === 'active' && record.sourceId === row.id && record.name === row.name)).map((row) => [row.id, row]));
+  const rows = local.flatMap((row) => {
+    const alias = aliases.get(row.id);
+    return alias !== undefined ? [alias] : retired.has(row.id) ? [] : [row];
+  });
+  rows.push(...organization.filter((row) => isOrgRelayId(row.id) && !records.some((record) => row.id === `org-${record.destinationId ?? ''}`)));
+  return rows;
+}
+
+export function publishConnectors(): void {
+  let rows: GateRow[];
+  let keys: Map<string, string>;
+  try {
+    const records = migrationRecords().filter((record) => record.phase !== 'rolled_back');
+    if (organization === null && records.some((record) => record.phase === 'active')) return;
+    const org = organization ?? [];
+    rows = publishedRows(records, org);
+    const active = new Set(records.filter((record) => record.phase === 'active').map((record) => record.sourceId));
+    const reserved = [...rows, ...local.filter((row) => active.has(row.id))];
+    keys = persistentServerKeys([...local, ...org.filter((row) => isOrgRelayId(row.id))], undefined, reserved);
+  }
+  catch (error) {
+    registerConnectors([]);
+    syncPluginServers([]);
+    throw error;
+  }
+  registerConnectors(rows, keys);
+  syncPluginServers(rows, { keys });
+}
+
+export function publishLocalConnectors(rows: readonly GateRow[]): void {
+  local = metadata(rows.filter((row) => !isOrgRelayId(row.id)));
+  publishConnectors();
+}
+
+export function publishOrgConnectors(rows: readonly GateRow[]): void {
+  organization = metadata(rows);
+  publishConnectors();
+}

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

@@ -0,0 +1,2 @@
+export const orgRelayId = (id: string): string => `org-${id}`;
+export const isOrgRelayId = (id: string): boolean => /^org-[A-Za-z0-9][A-Za-z0-9_-]{10}$/.test(id);

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

@@ -0,0 +1,96 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { JSONRPCNotificationSchema, ServerNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
+import { isRecord } from '@metro-labs/core/is-record';
+import type { MigrationOperation } from './migration-operations.js';
+
+export const isRelaySse = (contentType: string | null | undefined): boolean => /^text\/event-stream\s*(?:;|$)/i.test(contentType ?? '');
+const MAX_FRAME = 64 * 1024;
+const NOTIFICATIONS = new Set(['notifications/tools/list_changed', 'notifications/resources/list_changed', 'notifications/prompts/list_changed', 'notifications/resources/updated', 'notifications/message']);
+
+export class PassiveSseListener {
+  forwarding = false;
+  private pending: Buffer[] = [];
+  private length = 0;
+  private data: string[] = [];
+  private fields = false;
+  private size = 0;
+  private unsafe = false;
+  private skipLf = false;
+  private first = true;
+  private readonly decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+
+  idle(): boolean { return !this.unsafe && this.length === 0 && !this.fields && !this.forwarding; }
+  keepaliveAllowed(): boolean { return this.unsafe || this.idle(); }
+
+  observe(chunk: Uint8Array): void {
+    if (this.unsafe) return;
+    this.scan(chunk);
+    if (this.unsafe) { this.pending = []; this.length = 0; this.data = []; }
+  }
+
+  private append(bytes: Uint8Array): void {
+    this.length += bytes.length;
+    if (this.length + this.size > MAX_FRAME) this.unsafe = true;
+    else if (bytes.length > 0) this.pending.push(Buffer.from(bytes));
+  }
+
+  private scan(bytes: Uint8Array): void {
+    let start = 0;
+    for (let at = 0; at < bytes.length; at += 1) {
+      if (at - start + this.length + this.size > MAX_FRAME) { this.unsafe = true; return; }
+      const byte = bytes[at];
+      if (this.skipLf && byte === 10) { this.skipLf = false; start = at + 1; continue; }
+      this.skipLf = false;
+      if (byte !== 10 && byte !== 13) continue;
+      this.append(bytes.subarray(start, at));
+      try { this.line(this.decoder.decode(Buffer.concat(this.pending, this.length)), this.length); }
+      catch { this.unsafe = true; }
+      this.pending = []; this.length = 0;
+      this.skipLf = byte === 13;
+      start = at + 1;
+      if (this.unsafe) return;
+    }
+    this.append(bytes.subarray(start));
+  }
+
+  private line(raw: string, length: number): void {
+    const line = this.first && raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+    this.first = false;
+    if (line === '') {
+      if (this.data.length > 0 && !this.notification()) this.unsafe = true;
+      this.data = []; this.fields = false; this.size = 0;
+      return;
+    }
+    if (line.startsWith(':')) return;
+    this.size += length;
+    if (this.size > MAX_FRAME) { this.unsafe = true; return; }
+    this.fields = true;
+    const colon = line.indexOf(':');
+    const field = colon < 0 ? line : line.slice(0, colon);
+    const value = colon < 0 ? '' : line.slice(colon + 1).replace(/^ /, '');
+    this.field(field, value);
+  }
+
+  private field(field: string, value: string): void {
+    if (field === 'data') this.data.push(value);
+    else if (field === 'event') { if (value !== '' && value !== 'message') this.unsafe = true; }
+    else if (field === 'retry') { if (!/^\d+$/.test(value)) this.unsafe = true; }
+    else this.unsafe = true;
+  }
+
+  private notification(): boolean {
+    const text = this.data.join('\n');
+    if (text === '') return true;
+    const value: unknown = JSON.parse(text);
+    return isRecord(value) && typeof value.method === 'string' && NOTIFICATIONS.has(value.method)
+      && JSONRPCNotificationSchema.safeParse(value).success && ServerNotificationSchema.safeParse(value).success;
+  }
+}
+
+export function passiveRelayListener(req: IncomingMessage, res: ServerResponse, upstream: Response, operation: MigrationOperation, stop: () => void): PassiveSseListener | undefined {
+  if (req.method !== 'GET' || req.headers['last-event-id'] !== undefined || req.headers['transfer-encoding'] !== undefined || Number(req.headers['content-length'] ?? 0) !== 0) return undefined;
+  if (upstream.status !== 200 || upstream.body === null || !isRelaySse(upstream.headers.get('content-type'))) return undefined;
+  const listener = new PassiveSseListener();
+  operation.passiveListener({ idle: () => listener.idle() && res.writableLength === 0 && !res.destroyed, stop });
+  return listener;
+}

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]));
+}

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

@@ -0,0 +1,11 @@
+import type { BlockedReason } from './relay-policy.js';
+import type { RelayTarget } from './relay-target.js';
+
+export interface RelaySession {
+  target: (force: boolean) => Promise<RelayTarget>;
+  current: () => RelayTarget;
+  blocker: () => BlockedReason;
+  signal: AbortSignal;
+  close: () => void;
+  dispatch?: (send: () => Promise<Response>, effectful?: boolean) => Promise<Response>;
+}

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

@@ -0,0 +1,4 @@
+export type RelayTarget =
+  | { kind: 'ok'; url: string; headers: Record<string, string> }
+  | { kind: 'missing' }
+  | { kind: 'signin' };