@abot-ai/socket 0.0.0-stage → 0.1.0

package/src/relay/relay-correlations.mjs

@@ -0,0 +1,96 @@
+import { randomUUID } from 'node:crypto';
+import { isRecord, relayError } from './relay-runtime-registration.mjs';
+
+const MAX_PENDING = 128;
+const RPC_TIMEOUT_MS = 30_000;
+
+function steeringKey(runtime, body) {
+  return JSON.stringify([runtime.generation, body.requestId, body.steerId]);
+}
+
+function matchesResponseIdentity(entry, body) {
+  const command = entry.command;
+  if (command.type === 'steer_request') {
+    return body.requestId === command.requestId && body.steerId === command.steerId
+      && typeof body.accepted === 'boolean';
+  }
+  if (typeof body.ok !== 'boolean') return false;
+  if (command.type === 'request.events.request' && body.requestId !== command.requestId) return false;
+  // Upload responses intentionally do not echo requestId in the existing runtime.
+  if (body.requestId !== undefined && body.requestId !== command.requestId) return false;
+  if (command.sessionId !== undefined && body.sessionId !== command.sessionId) return false;
+  if (body.sessionId !== undefined && command.sessionId === undefined) return false;
+  if (command.type === 'session.message.delete.request' && body.messageId !== command.messageId) return false;
+  if (command.type === 'session.messages.clear.request' && typeof body.cleared !== 'boolean') return false;
+  if (['session.delete.request', 'session.message.delete.request'].includes(command.type)
+    && typeof body.deleted !== 'boolean') return false;
+  if (command.type === 'request.events.request' && body.ok) {
+    if (!Array.isArray(body.events) || body.events.length > 8192) return false;
+    if (body.events.some(event => !isRecord(event) || (event.requestId !== undefined && event.requestId !== command.requestId))) return false;
+  }
+  return true;
+}
+
+export class RelayCorrelations {
+  constructor({ now, respond, unknown }) {
+    this.now = now;
+    this.respond = respond;
+    this.unknown = unknown;
+    this.pending = new Map();
+    this.steering = new Map();
+  }
+
+  create(client, runtime, id, command, expectedType, lifecycle = {}) {
+    if (this.pending.size >= MAX_PENDING) throw relayError('pending_capacity');
+    const steerKey = command.type === 'steer_request' ? steeringKey(runtime, command) : null;
+    if (steerKey && this.steering.has(steerKey)) throw relayError('duplicate_steer_id');
+    const correlationId = randomUUID();
+    // Retain routing identity, never attachment bytes, prompts or conversation data.
+    const identity = { type: command.type, requestId: command.requestId,
+      sessionId: command.sessionId, steerId: command.steerId, messageId: command.messageId };
+    const entry = { client, runtime, id, command: identity, expectedType, correlationId,
+      expiresAt: this.now() + RPC_TIMEOUT_MS, steerKey, lifecycle };
+    this.pending.set(correlationId, entry);
+    if (steerKey) this.steering.set(steerKey, correlationId);
+    return entry;
+  }
+
+  remove(entry) {
+    this.pending.delete(entry.correlationId);
+    if (entry.steerKey) this.steering.delete(entry.steerKey);
+    entry.lifecycle.removed?.();
+  }
+
+  receive(runtime, body) {
+    const correlationId = body.type === 'steer_ack'
+      ? this.steering.get(steeringKey(runtime, body)) : body.correlationId;
+    const entry = this.pending.get(correlationId);
+    if (!entry || entry.runtime !== runtime || entry.expectedType !== body.type) return false;
+    if (entry.expiresAt <= this.now() || !matchesResponseIdentity(entry, body)) return false;
+    // An invalid reply must never consume the genuine request's pending record.
+    this.remove(entry);
+    (entry.lifecycle.respond ?? this.respond)(entry, body);
+    return true;
+  }
+
+  fail(entry) {
+    if (!this.pending.has(entry.correlationId)) return;
+    this.remove(entry);
+    (entry.lifecycle.unknown ?? this.unknown)(entry);
+  }
+
+  disconnectRuntime(runtime) {
+    for (const entry of this.pending.values()) if (entry.runtime === runtime) this.fail(entry);
+  }
+
+  disconnectClient(client) {
+    for (const entry of this.pending.values()) {
+      if (entry.client !== client || entry.lifecycle.retainOnClientDisconnect) continue;
+      this.remove(entry);
+    }
+  }
+
+  prune() {
+    for (const entry of this.pending.values()) if (entry.expiresAt <= this.now()) this.fail(entry);
+  }
+}

package/src/relay/relay-model-catalog.mjs

@@ -0,0 +1,69 @@
+const MODALITIES = new Set(['text', 'image', 'audio']);
+const EXECUTION_POLICIES = new Set(['supervisor-worker-v1', 'execution-agent-v1']);
+
+function invalidCatalog() {
+  throw Object.assign(new Error('invalid_model_catalog'), { code: 'invalid_model_catalog' });
+}
+
+function catalogRecord(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) invalidCatalog();
+  return value;
+}
+
+function catalogString(value, maximum) {
+  if (typeof value !== 'string' || !value.trim() || value.length > maximum) invalidCatalog();
+  if (/[\u0000-\u001f\u007f]/u.test(value)) invalidCatalog();
+  return value;
+}
+
+function catalogBoolean(value) {
+  if (typeof value !== 'boolean') invalidCatalog();
+  return value;
+}
+
+function catalogModalities(value) {
+  if (!Array.isArray(value) || value.length > 3 || value.some(item => !MODALITIES.has(item))) invalidCatalog();
+  return [...new Set(value)];
+}
+
+function catalogCapabilities(value) {
+  catalogRecord(value);
+  const result = {};
+  for (const key of ['inputModalities', 'outputModalities']) {
+    if (value[key] !== undefined) result[key] = catalogModalities(value[key]);
+  }
+  return result;
+}
+
+function catalogProfile(value) {
+  catalogRecord(value);
+  const result = { id: catalogString(value.id, 160), label: catalogString(value.label, 240) };
+  // Mirror display/capability fields projected by loadRuntimeModelCatalog, never provider config.
+  for (const [field, maximum] of [['providerId', 160], ['provider', 160], ['model', 512]]) {
+    if (value[field] !== undefined) result[field] = catalogString(value[field], maximum);
+  }
+  for (const field of ['supportsThinking', 'supportsImageInput']) {
+    if (value[field] !== undefined) result[field] = catalogBoolean(value[field]);
+  }
+  if (value.executionPolicy !== undefined) {
+    if (!EXECUTION_POLICIES.has(value.executionPolicy)) invalidCatalog();
+    result.executionPolicy = value.executionPolicy;
+  }
+  if (value.reasoningControls !== undefined) {
+    catalogRecord(value.reasoningControls);
+    result.reasoningControls = { budgetTokens: catalogBoolean(value.reasoningControls.budgetTokens) };
+  }
+  if (value.capabilities !== undefined) result.capabilities = catalogCapabilities(value.capabilities);
+  return result;
+}
+
+export function parseRuntimeModelCatalog(value) {
+  catalogRecord(value);
+  if (value.schemaVersion !== 1) invalidCatalog();
+  const defaultProfileId = catalogString(value.defaultProfileId, 160);
+  if (!Array.isArray(value.profiles) || value.profiles.length === 0 || value.profiles.length > 128) invalidCatalog();
+  const profiles = value.profiles.map(catalogProfile);
+  const ids = new Set(profiles.map(profile => profile.id));
+  if (ids.size !== profiles.length || !ids.has(defaultProfileId)) invalidCatalog();
+  return { schemaVersion: 1, defaultProfileId, profiles };
+}

package/src/relay/relay-requests.mjs

@@ -0,0 +1,155 @@
+import { isRelayId, relayError } from './relay-runtime-registration.mjs';
+
+const MAX_ACTIVE = 128;
+const MAX_BINDINGS = 512;
+const BINDING_TTL_MS = 12 * 60 * 60 * 1000;
+const APPROVAL_TTL_MS = 5 * 60 * 1000;
+const STREAM_TYPES = new Set(['token', 'event', 'completed', 'failed', 'session_message']);
+const keyFor = (runtimeId, requestId) => JSON.stringify([runtimeId, requestId]);
+
+function canConsumeObservedApproval(approval, approved, now) {
+  if (approval.state === 'expired') return approved === false;
+  if (approval.state !== 'pending') return false;
+  if (approval.expiresAt <= now) return approved === false;
+  return true;
+}
+
+export class RelayRequests {
+  constructor({ now, event, unknown, observe = () => {} }) {
+    this.now = now;
+    this.event = event;
+    this.unknown = unknown;
+    this.observe = observe;
+    this.bindings = new Map();
+  }
+
+  create(client, runtime, command) {
+    const key = keyFor(runtime.runtimeId, command.requestId);
+    if (this.bindings.has(key)) throw relayError('request_id_conflict');
+    if (this.bindings.size >= MAX_BINDINGS) throw relayError('request_capacity');
+    const activeCount = [...this.bindings.values()].filter(record => record.state === 'active').length;
+    if (activeCount >= MAX_ACTIVE) throw relayError('active_request_capacity');
+    const record = { key, subject: client.subject, deviceId: client.sessionId, runtime, requestId: command.requestId,
+      sessionId: command.sessionId, state: 'active', subscribers: new Set([client]),
+      expiresAt: this.now() + BINDING_TTL_MS, approvals: new Map(), steering: new Set() };
+    this.bindings.set(key, record);
+    return record;
+  }
+
+  owned(client, runtime, requestId, requireActive = false) {
+    const record = this.bindings.get(keyFor(runtime.runtimeId, requestId));
+    if (!record || record.subject !== client.subject) throw relayError('request_not_owned');
+    if (requireActive && (record.state !== 'active' || record.runtime !== runtime)) {
+      throw relayError('request_not_active');
+    }
+    return record;
+  }
+
+  subscribe(client, runtime, requestId) {
+    const record = this.owned(client, runtime, requestId);
+    record.subscribers.add(client);
+    return record;
+  }
+
+  reserveSteering(client, runtime, body) {
+    const record = this.owned(client, runtime, body.requestId, true);
+    if (!runtime.features.includes('request_steering_v1')) throw relayError('steering_unsupported');
+    if (record.steering.has(body.steerId)) throw relayError('duplicate_steer_id');
+    if (record.steering.size >= 128) throw relayError('steering_capacity');
+    record.steering.add(body.steerId);
+  }
+
+  consumeApproval(client, runtime, body) {
+    for (const record of this.bindings.values()) {
+      if (record.runtime !== runtime || record.subject !== client.subject || record.state !== 'active') continue;
+      const approval = record.approvals.get(body.approvalId);
+      if (!approval) continue;
+      if (!canConsumeObservedApproval(approval, body.approved, this.now())) throw relayError('approval_not_pending');
+      // Consume before send: failure cannot make a possibly executed decision reusable.
+      approval.state = 'used';
+      return record;
+    }
+    throw relayError('approval_not_pending');
+  }
+
+  receive(runtime, body) {
+    if (!STREAM_TYPES.has(body.type) || !isRelayId(body.requestId)) return false;
+    const record = this.bindings.get(keyFor(runtime.runtimeId, body.requestId));
+    if (!record || record.runtime !== runtime || record.state !== 'active') return false;
+    if (!this.acceptSessionIdentity(record, body)) return false;
+    if (body.type === 'event' && (typeof body.name !== 'string' || body.name.length > 256)) return false;
+    if (body.type === 'event' && body.name === 'tool.approval.required') {
+      if (!this.observeApproval(record, body.approvalId)) return false;
+    }
+    if (body.type === 'event' && ['tool.approval.granted', 'tool.approval.rejected'].includes(body.name)) {
+      const approval = record.approvals.get(body.approvalId);
+      if (approval) approval.state = 'closed';
+    }
+    if (body.type === 'completed' || body.type === 'failed') {
+      record.state = 'terminal';
+      record.expiresAt = this.now() + BINDING_TTL_MS;
+      this.invalidateApprovals(record);
+    }
+    try {
+      this.observe({ deviceId: record.deviceId, runtimeId: runtime.runtimeId,
+        sessionId: record.sessionId, requestId: record.requestId }, body);
+    } catch { /* Notification storage must not interrupt the chat stream. */ }
+    for (const client of record.subscribers) this.event(client, runtime.runtimeId, body);
+    return true;
+  }
+
+  acceptSessionIdentity(record, body) {
+    if (body.sessionId === undefined || body.sessionId === null) return true;
+    if (!isRelayId(body.sessionId)) return false;
+    if (record.sessionId && record.sessionId !== body.sessionId) return false;
+    record.sessionId = body.sessionId;
+    return true;
+  }
+
+  observeApproval(record, approvalId) {
+    if (typeof approvalId !== 'string' || !approvalId || approvalId.length > 512) return false;
+    const existing = record.approvals.get(approvalId);
+    if (existing) return existing.state === 'pending' && existing.expiresAt > this.now();
+    if (record.approvals.size >= 64) return false;
+    // Approval IDs may not be reused between simultaneous requests on one runtime.
+    for (const other of this.bindings.values()) {
+      if (other.runtime === record.runtime && other.approvals.has(approvalId)) return false;
+    }
+    record.approvals.set(approvalId, { state: 'pending', expiresAt: this.now() + APPROVAL_TTL_MS });
+    return true;
+  }
+
+  invalidateApprovals(record) {
+    for (const approval of record.approvals.values()) approval.state = 'closed';
+  }
+
+  markUnknown(record, notify = true) {
+    if (record.state !== 'active') return;
+    record.state = 'unknown';
+    record.expiresAt = this.now() + BINDING_TTL_MS;
+    this.invalidateApprovals(record);
+    if (notify) for (const client of record.subscribers) this.unknown(client, record);
+  }
+
+  disconnectRuntime(runtime) {
+    for (const record of this.bindings.values()) if (record.runtime === runtime) this.markUnknown(record);
+  }
+
+  disconnectClient(client) {
+    for (const record of this.bindings.values()) record.subscribers.delete(client);
+  }
+
+  prune() {
+    for (const record of this.bindings.values()) {
+      for (const approval of record.approvals.values()) {
+        if (approval.expiresAt <= this.now() && approval.state === 'pending') approval.state = 'expired';
+      }
+      if (record.expiresAt > this.now()) continue;
+      if (record.state === 'active') {
+        this.markUnknown(record);
+        continue;
+      }
+      this.bindings.delete(record.key);
+    }
+  }
+}

package/src/relay/relay-runtime-registration.mjs

@@ -0,0 +1,49 @@
+import { parseRuntimeModelCatalog } from './relay-model-catalog.mjs';
+
+const MODES = new Set(['ask', 'full_access', 'full_plus']);
+
+export function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function isRelayId(value) {
+  return typeof value === 'string' && /^[A-Za-z0-9_.:-]{1,128}$/.test(value);
+}
+
+export function relayError(code) {
+  return Object.assign(new Error(code), { code });
+}
+
+export function isBoundedRuntimeFrame(body) {
+  if (!isRecord(body) || typeof body.type !== 'string' || body.type.length > 128) return false;
+  try {
+    return Buffer.byteLength(JSON.stringify(body)) <= 16 * 1024 * 1024;
+  } catch {
+    return false;
+  }
+}
+
+export function validateRuntimeGrant(grant) {
+  if (!isRecord(grant) || !isRelayId(grant.runtimeId)) throw relayError('invalid_runtime_grant');
+  const allowedModes = grant.allowedModes ?? ['ask'];
+  if (!Array.isArray(allowedModes) || allowedModes.length === 0 || allowedModes.length > 3) {
+    throw relayError('invalid_runtime_grant');
+  }
+  if (allowedModes.some(mode => !MODES.has(mode))) throw relayError('invalid_runtime_grant');
+  return { runtimeId: grant.runtimeId, allowedModes: [...new Set(allowedModes)] };
+}
+
+function boundedLabel(value, length) {
+  return typeof value === 'string' && value.trim().length > 0 && value.length <= length;
+}
+
+export function parseRuntimeRegistration(body, runtimeId) {
+  if (body.type !== 'register' || body.agentId !== runtimeId) throw relayError('runtime_identity_mismatch');
+  if (Buffer.byteLength(JSON.stringify(body)) > 128 * 1024) throw relayError('registration_too_large');
+  const features = body.features ?? [];
+  if (!Array.isArray(features) || features.length > 64) throw relayError('invalid_runtime_features');
+  if (features.some(feature => !boundedLabel(feature, 128))) throw relayError('invalid_runtime_features');
+  if (new Set(features).size !== features.length) throw relayError('invalid_runtime_features');
+  const modelCatalog = body.modelCatalog === undefined ? null : parseRuntimeModelCatalog(body.modelCatalog);
+  return { features: [...features], modelCatalog };
+}

package/src/relay/relay-session-mutations.mjs

@@ -0,0 +1,88 @@
+import { expectedResponseType } from '../protocol/protocol.mjs';
+import { relayError } from './relay-runtime-registration.mjs';
+
+const MUTATIONS = new Set([
+  'session.delete.request', 'session.messages.clear.request', 'session.message.delete.request',
+]);
+const MUTATION_TIMEOUT_MS = 30_000;
+
+export function isSessionMutation(type) {
+  return MUTATIONS.has(type);
+}
+
+const sessionKey = (runtime, sessionId) => JSON.stringify([runtime.generation, sessionId]);
+
+/** A bounded read-before-delete guard, not an atomic lock over independent clients. */
+export class RelaySessionMutations {
+  constructor({ now, correlations, requests, transmit, connected, error, respond }) {
+    Object.assign(this, { now, correlations, requests, transmit, connected, error, respond });
+    this.pending = new Map();
+  }
+
+  assertNoPending(runtime, sessionId) {
+    if (this.pending.has(sessionKey(runtime, sessionId))) throw relayError('session_mutation_pending');
+  }
+
+  assertNoObservedWork(runtime, sessionId) {
+    for (const record of this.requests.bindings.values()) {
+      if (record.runtime !== runtime || record.sessionId !== sessionId) continue;
+      if (record.state !== 'terminal') throw relayError('session_busy');
+    }
+    for (const entry of this.correlations.pending.values()) {
+      if (entry.runtime === runtime && entry.command.sessionId === sessionId
+        && entry.command.type === 'attachment.upload.request') throw relayError('session_busy');
+    }
+  }
+
+  dispatch(client, runtime, id, command) {
+    this.assertNoPending(runtime, command.sessionId);
+    this.assertNoObservedWork(runtime, command.sessionId);
+    const operation = { client, runtime, id, command,
+      expiresAt: this.now() + MUTATION_TIMEOUT_MS, key: sessionKey(runtime, command.sessionId) };
+    this.snapshot(operation);
+  }
+
+  snapshot(operation) {
+    const command = { type: 'session.snapshot.request', sessionId: operation.command.sessionId,
+      includeRequests: true };
+    this.send(operation, command, body => this.afterSnapshot(operation, body));
+  }
+
+  afterSnapshot(operation, body) {
+    if (!this.connected(operation.client)) return;
+    try {
+      if (this.now() >= operation.expiresAt) throw relayError('session_state_unavailable');
+      this.assertNoObservedWork(operation.runtime, operation.command.sessionId);
+      if (!body.ok) throw relayError(body.error === 'session_not_found' ? 'session_not_found' : 'session_state_unavailable');
+      // The existing bridge returns every request and no continuation cursor.
+      // A partial/newer contract cannot prove idleness; never guess pagination.
+      if (!Array.isArray(body.requests) || body.nextCursor !== null) throw relayError('session_state_unavailable');
+      for (const request of body.requests) {
+        if (!request || typeof request !== 'object') throw relayError('session_state_unavailable');
+        if (request.sessionId !== operation.command.sessionId) throw relayError('session_state_unavailable');
+        if (!['completed', 'failed'].includes(request.status)) throw relayError('session_busy');
+      }
+      this.send(operation, operation.command, result => this.respond(operation, result));
+    } catch (error) {
+      this.error(operation, error.code ?? 'session_state_unavailable');
+    }
+  }
+
+  send(operation, command, respond) {
+    const entry = this.correlations.create(operation.client, operation.runtime, operation.id,
+      command, expectedResponseType(command.type), {
+        respond: (_entry, body) => respond(body),
+        unknown: () => this.error(operation, 'outcome_unknown'),
+        removed: () => {
+          if (this.pending.get(operation.key) === operation) this.pending.delete(operation.key);
+        },
+        // Keep the lock while an already sent mutation may still be running.
+        retainOnClientDisconnect: true,
+      });
+    entry.expiresAt = operation.expiresAt;
+    this.pending.set(operation.key, operation);
+    if (!this.transmit(operation.runtime.peer, { ...command, correlationId: entry.correlationId })) {
+      this.correlations.fail(entry);
+    }
+  }
+}

package/src/relay/relay.mjs

@@ -0,0 +1,202 @@
+import { randomUUID } from 'node:crypto';
+import { normalizeClientCommand, expectedResponseType } from '../protocol/protocol.mjs';
+import { createRelayClient, admitRelayCommand } from './relay-client-admission.mjs';
+import { RelayCorrelations } from './relay-correlations.mjs';
+import { RelayRequests } from './relay-requests.mjs';
+import { RelaySessionMutations, isSessionMutation } from './relay-session-mutations.mjs';
+import { isBoundedRuntimeFrame, isRelayId, parseRuntimeRegistration,
+  validateRuntimeGrant, relayError } from './relay-runtime-registration.mjs';
+
+export class Relay {
+  constructor({ now = Date.now, send, close, observeRequest }) {
+    this.now = now;
+    this.send = send;
+    this.close = close;
+    this.clients = new Map();
+    this.runtimes = new Map();
+    this.runtimePeers = new Map();
+    this.requests = new RelayRequests({ now, observe: observeRequest,
+      event: (client, runtimeId, body) => this.deliver(client, { type: 'relay.event', runtimeId, body }),
+      unknown: (client, record) => this.error(client.peer, undefined, record.runtime.runtimeId,
+        'outcome_unknown', { requestId: record.requestId }),
+    });
+    this.correlations = new RelayCorrelations({ now,
+      respond: (entry, body) => this.deliver(entry.client, { type: 'relay.response', id: entry.id,
+        runtimeId: entry.runtime.runtimeId, body }),
+      unknown: entry => this.error(entry.client.peer, entry.id, entry.runtime.runtimeId, 'outcome_unknown'),
+    });
+    this.sessionMutations = new RelaySessionMutations({ now, correlations: this.correlations,
+      requests: this.requests, transmit: (peer, body) => this.transmit(peer, body),
+      connected: client => this.clients.get(client.peer) === client,
+      error: (operation, code) => this.error(operation.client.peer, operation.id, operation.runtime.runtimeId, code),
+      respond: (operation, body) => this.deliver(operation.client, { type: 'relay.response',
+        id: operation.id, runtimeId: operation.runtime.runtimeId, body }),
+    });
+  }
+
+  transmit(peer, body) {
+    try { return this.send(peer, body) === true; } catch { return false; }
+  }
+
+  terminate(peer, reason) {
+    this.disconnect(peer);
+    try { this.close(peer, 1008, reason); } catch { /* State is already detached. */ }
+  }
+
+  deliver(client, body) {
+    if (this.clients.get(client.peer) !== client) return false;
+    if (this.transmit(client.peer, body)) return true;
+    this.terminate(client.peer, 'transport_unavailable');
+    return false;
+  }
+
+  error(peer, id, runtimeId, code, body) {
+    const client = this.clients.get(peer);
+    if (!client) return;
+    this.deliver(client, { type: 'relay.error', ...(isRelayId(id) ? { id } : {}),
+      ...(isRelayId(runtimeId) ? { runtimeId } : {}), code, ...(body ? { body } : {}) });
+  }
+
+  attachRuntime(peer, grant) {
+    this.prune();
+    if (this.runtimePeers.has(peer) || this.clients.has(peer)) return false;
+    try {
+      const identity = validateRuntimeGrant(grant);
+      if (this.runtimes.has(identity.runtimeId) || this.runtimes.size >= 32) return false;
+      const runtime = { ...identity, peer, generation: randomUUID(), registered: false,
+        registerBy: this.now() + 5_000, features: [], modelCatalog: null };
+      this.runtimePeers.set(peer, runtime);
+      this.runtimes.set(runtime.runtimeId, runtime);
+      return true;
+    } catch { return false; }
+  }
+
+  attachClient(peer, identity) {
+    this.prune();
+    if (this.clients.has(peer) || this.runtimePeers.has(peer) || this.clients.size >= 128) return false;
+    try {
+      this.clients.set(peer, createRelayClient(peer, identity, this.now()));
+      return true;
+    } catch { return false; }
+  }
+
+  runtimeSnapshot(allowedRuntimeIds) {
+    if (!Array.isArray(allowedRuntimeIds) || allowedRuntimeIds.length > 32) return [];
+    return [...new Set(allowedRuntimeIds.filter(isRelayId))].map(runtimeId => {
+      const runtime = this.runtimes.get(runtimeId);
+      const online = runtime?.registered === true;
+      return { runtimeId, online,
+        modelCatalog: online ? structuredClone(runtime.modelCatalog) : null,
+        features: online ? [...runtime.features] : [] };
+    });
+  }
+
+  register(runtime, body) {
+    if (runtime.registered) throw relayError('duplicate_registration');
+    const registration = parseRuntimeRegistration(body, runtime.runtimeId);
+    Object.assign(runtime, registration, { registered: true });
+    const reply = { type: 'registered', agentId: runtime.runtimeId, ok: true,
+      modelCatalog: { accepted: true, source: runtime.modelCatalog ? 'runtime' : 'legacy' },
+      features: runtime.features };
+    if (!this.transmit(runtime.peer, reply)) this.terminate(runtime.peer, 'transport_unavailable');
+  }
+
+  runtimeMessage(peer, body) {
+    this.prune();
+    const runtime = this.runtimePeers.get(peer);
+    if (!runtime || this.runtimes.get(runtime.runtimeId) !== runtime) return;
+    if (!isBoundedRuntimeFrame(body)) return this.terminate(peer, 'invalid_runtime_frame');
+    try {
+      if (body.type === 'register') return this.register(runtime, body);
+      if (!runtime.registered) return this.terminate(peer, 'registration_required');
+      if (this.correlations.receive(runtime, body)) return;
+      this.requests.receive(runtime, body);
+    } catch (error) {
+      this.terminate(peer, error.code ?? 'invalid_runtime_frame');
+    }
+  }
+
+  clientMessage(peer, message) {
+    this.prune();
+    const client = this.clients.get(peer);
+    if (!client) return;
+    try {
+      admitRelayCommand(client, message, this.now());
+      const runtime = this.runtimes.get(message.runtimeId);
+      if (!runtime?.registered) throw relayError('runtime_offline');
+      const command = normalizeClientCommand(message.body, runtime.allowedModes);
+      this.dispatch(client, runtime, message.id, command);
+    } catch (error) {
+      this.error(peer, message?.id, message?.runtimeId, error.code ?? 'invalid_command');
+    }
+  }
+
+  acknowledge(client, runtime, id, body) {
+    this.deliver(client, { type: 'relay.ack', id, runtimeId: runtime.runtimeId, body });
+  }
+
+  dispatch(client, runtime, id, command) {
+    if (isSessionMutation(command.type)) return this.sessionMutations.dispatch(client, runtime, id, command);
+    if (['run_request', 'attachment.upload.request'].includes(command.type)) {
+      this.sessionMutations.assertNoPending(runtime, command.sessionId);
+    }
+    if (command.type === 'run_request') return this.dispatchRun(client, runtime, id, command);
+    if (command.type === 'subscribe_request') {
+      this.requests.subscribe(client, runtime, command.requestId);
+      return this.acknowledge(client, runtime, id, { requestId: command.requestId, status: 'subscribed' });
+    }
+    if (command.type === 'tool_approval_response') return this.dispatchApproval(client, runtime, id, command);
+    if (command.type === 'steer_request') return this.dispatchSteering(client, runtime, id, command);
+    const expectedType = expectedResponseType(command.type);
+    if (!expectedType) throw relayError('unsupported_command');
+    const entry = this.correlations.create(client, runtime, id, command, expectedType);
+    const frame = { ...command, correlationId: entry.correlationId };
+    if (!this.transmit(runtime.peer, frame)) this.correlations.fail(entry);
+  }
+
+  dispatchRun(client, runtime, id, command) {
+    const record = this.requests.create(client, runtime, command);
+    if (!this.transmit(runtime.peer, command)) {
+      this.requests.markUnknown(record, false);
+      return this.error(client.peer, id, runtime.runtimeId, 'outcome_unknown');
+    }
+    this.acknowledge(client, runtime, id, { requestId: command.requestId, status: 'dispatched' });
+  }
+
+  dispatchApproval(client, runtime, id, command) {
+    this.requests.consumeApproval(client, runtime, command);
+    if (!this.transmit(runtime.peer, command)) return this.error(client.peer, id, runtime.runtimeId, 'outcome_unknown');
+    this.acknowledge(client, runtime, id, { approvalId: command.approvalId, status: 'dispatched' });
+  }
+
+  dispatchSteering(client, runtime, id, command) {
+    this.requests.owned(client, runtime, command.requestId, true);
+    const entry = this.correlations.create(client, runtime, id, command, 'steer_ack');
+    try { this.requests.reserveSteering(client, runtime, command); }
+    catch (error) { this.correlations.remove(entry); throw error; }
+    if (!this.transmit(runtime.peer, command)) this.correlations.fail(entry);
+  }
+
+  disconnect(peer) {
+    const client = this.clients.get(peer);
+    if (client) {
+      this.clients.delete(peer);
+      this.requests.disconnectClient(client);
+      this.correlations.disconnectClient(client);
+    }
+    const runtime = this.runtimePeers.get(peer);
+    if (!runtime) return;
+    this.runtimePeers.delete(peer);
+    if (this.runtimes.get(runtime.runtimeId) === runtime) this.runtimes.delete(runtime.runtimeId);
+    this.correlations.disconnectRuntime(runtime);
+    this.requests.disconnectRuntime(runtime);
+  }
+
+  prune() {
+    for (const runtime of this.runtimePeers.values()) {
+      if (!runtime.registered && runtime.registerBy <= this.now()) this.terminate(runtime.peer, 'registration_timeout');
+    }
+    this.correlations.prune();
+    this.requests.prune();
+  }
+}