@abot-ai/socket 0.0.0-stage → 0.2.0

package/src/protocol/protocol-validation.mjs

@@ -0,0 +1,137 @@
+import { Buffer } from 'node:buffer';
+
+export const MAX_MESSAGE_BYTES = 16 * 1024 * 1024;
+export const MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+export const MAX_TEXT_BYTES = 128 * 1024;
+const MAX_BASE64_LENGTH = 4 * Math.ceil(MAX_ATTACHMENT_BYTES / 3);
+const MIME_TYPES = new Map([
+  ['image/png', 'image'], ['image/jpeg', 'image'], ['image/webp', 'image'],
+  ['application/pdf', 'file'],
+  ['application/vnd.openxmlformats-officedocument.wordprocessingml.document', 'file'],
+  ['application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 'file'],
+  ['application/vnd.openxmlformats-officedocument.presentationml.presentation', 'file'],
+  ['text/plain', 'file'], ['text/csv', 'file'], ['text/markdown', 'file'],
+  ['application/json', 'file'], ['application/rtf', 'file'],
+]);
+
+export function fail(code = 'invalid_command') {
+  throw Object.assign(new Error(code), { code });
+}
+
+export function record(value, allowed) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail();
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) fail();
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (Reflect.ownKeys(descriptors).some((key) => typeof key !== 'string')) fail();
+  for (const [key, descriptor] of Object.entries(descriptors)) {
+    if (!allowed.includes(key) || !descriptor.enumerable || !('value' in descriptor)) fail();
+  }
+  return value;
+}
+
+export function string(value, maximum, { nonempty = true, controls = false } = {}) {
+  if (typeof value !== 'string' || Buffer.byteLength(value, 'utf8') > maximum) fail();
+  if (nonempty && !value.trim()) fail();
+  if (!controls && /[\u0000-\u001f\u007f]/u.test(value)) fail();
+  return value;
+}
+
+export function id(value) {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9_.:-]{1,128}$/u.test(value)) fail();
+  return value;
+}
+
+export function approvalId(value) {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9_.:-]{1,512}$/u.test(value)) fail();
+  return value;
+}
+
+export function integer(value, minimum = 0, maximum = Number.MAX_SAFE_INTEGER) {
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) fail();
+  return value;
+}
+
+export function boolean(value) {
+  if (typeof value !== 'boolean') fail();
+  return value;
+}
+
+export function optional(source, target, key, validate) {
+  if (Object.hasOwn(source, key)) target[key] = validate(source[key]);
+}
+
+export function mime(value) {
+  const normalized = string(value, 160).split(';', 1)[0].trim().toLowerCase();
+  if (!MIME_TYPES.has(normalized)) fail();
+  return normalized;
+}
+
+export function kind(value) {
+  if (value !== 'image' && value !== 'file') fail();
+  return value;
+}
+
+export function attachment(value) {
+  record(value, ['id', 'kind', 'mimeType', 'storageRef', 'name', 'size']);
+  const result = {
+    id: id(value.id), kind: kind(value.kind), mimeType: mime(value.mimeType),
+    storageRef: string(value.storageRef, 2048),
+  };
+  if (MIME_TYPES.get(result.mimeType) !== result.kind) fail();
+  optional(value, result, 'name', (name) => string(name, 1024));
+  optional(value, result, 'size', (size) => integer(size, 0, MAX_ATTACHMENT_BYTES));
+  return result;
+}
+
+export function attachments(value) {
+  if (!Array.isArray(value) || value.length > 32) fail();
+  // Sparse arrays and custom/accessor properties are not a JSON attachment list.
+  if (Object.getPrototypeOf(value) !== Array.prototype) fail();
+  const keys = Reflect.ownKeys(value);
+  if (keys.length !== value.length + 1) fail();
+  for (let index = 0; index < value.length; index += 1) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+    if (!descriptor || !('value' in descriptor)) fail();
+  }
+  return Array.from(value, attachment);
+}
+
+export function base64(value) {
+  if (typeof value !== 'string' || !value || value.length > MAX_BASE64_LENGTH) fail();
+  if (value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/u.test(value)) fail();
+  const bytes = Buffer.from(value, 'base64');
+  if (bytes.length > MAX_ATTACHMENT_BYTES || bytes.toString('base64') !== value) fail();
+  return value;
+}
+
+export function modelPreference(value) {
+  record(value, ['profileId', 'scope']);
+  const result = { profileId: string(value.profileId, 256) };
+  optional(value, result, 'scope', (scope) => {
+    if (scope !== 'main' && scope !== 'all') fail();
+    return scope;
+  });
+  return result;
+}
+
+export function reasoningPreference(value) {
+  record(value, ['profileId', 'mode', 'budgetTokens']);
+  const result = { profileId: string(value.profileId, 256), mode: value.mode };
+  if (!['off', 'server-default', 'budget'].includes(value.mode)) fail();
+  if (value.mode !== 'budget' && Object.hasOwn(value, 'budgetTokens')) fail();
+  if (value.mode === 'budget') result.budgetTokens = integer(value.budgetTokens, 0, 2_147_483_647);
+  return result;
+}
+
+export function upload(value) {
+  const result = {
+    type: value.type, sessionId: id(value.sessionId), mimeType: mime(value.mimeType),
+    data: base64(value.data),
+  };
+  optional(value, result, 'requestId', id);
+  optional(value, result, 'kind', kind);
+  optional(value, result, 'name', (name) => string(name, 1024));
+  if (result.kind && MIME_TYPES.get(result.mimeType) !== result.kind) fail();
+  return result;
+}

package/src/protocol/protocol.mjs

@@ -0,0 +1,120 @@
+import { Buffer } from 'node:buffer';
+import {
+  MAX_MESSAGE_BYTES, MAX_TEXT_BYTES, fail, record, string, id, approvalId, integer,
+  boolean, optional, attachment, attachments, modelPreference, reasoningPreference, upload,
+} from './protocol-validation.mjs';
+import { APPROVAL_FIELDS, APPROVAL_RESPONSES, durableApprovalMode,
+  isApprovalCommand, normalizeApprovalCommand } from './approval-protocol.mjs';
+import { SPARK_OPEN_REQUEST, SPARK_OPEN_RESPONSE } from './spark-chat-protocol.mjs';
+
+export { MAX_MESSAGE_BYTES, MAX_ATTACHMENT_BYTES, MAX_TEXT_BYTES } from './protocol-validation.mjs';
+
+const FIELDS = Object.freeze({
+  [SPARK_OPEN_REQUEST]: [],
+  run_request: ['requestId', 'sessionId', 'input', 'text', 'agentMode', 'modelPreference', 'reasoningPreference', 'toolPermissionMode', 'attachments', 'approvalMode'],
+  ...APPROVAL_FIELDS,
+  steer_request: ['requestId', 'steerId', 'text'],
+  tool_approval_response: ['approvalId', 'approved', 'reason'],
+  'request.events.request': ['requestId', 'afterSeq'],
+  'session.list.request': ['limit', 'cursor'],
+  'session.snapshot.request': ['sessionId', 'afterMessageId', 'includeRequests'],
+  'session.delete.request': ['sessionId'],
+  'session.messages.clear.request': ['sessionId'],
+  'session.message.delete.request': ['sessionId', 'messageId'],
+  'attachment.upload.request': ['sessionId', 'requestId', 'mimeType', 'kind', 'name', 'data'],
+  'attachment.fetch.request': ['sessionId', 'attachment'],
+  subscribe_request: ['requestId'],
+});
+const RESPONSES = Object.freeze({
+  [SPARK_OPEN_REQUEST]: SPARK_OPEN_RESPONSE,
+  ...APPROVAL_RESPONSES,
+  'request.events.request': 'request.events.response',
+  'session.list.request': 'session.list.response',
+  'session.snapshot.request': 'session.snapshot.response',
+  'session.delete.request': 'session.delete.response',
+  'session.messages.clear.request': 'session.messages.clear.response',
+  'session.message.delete.request': 'session.message.delete.response',
+  'attachment.upload.request': 'attachment.upload.response',
+  'attachment.fetch.request': 'attachment.fetch.response',
+});
+const MODES = ['ask', 'full_access', 'full_plus'];
+const text = (value) => string(value, MAX_TEXT_BYTES, { controls: true });
+
+export function expectedResponseType(type) {
+  return typeof type === 'string' && Object.hasOwn(RESPONSES, type) ? RESPONSES[type] : undefined;
+}
+
+function run(value, allowedModes) {
+  const result = { type: value.type, requestId: id(value.requestId), sessionId: id(value.sessionId) };
+  if (!Object.hasOwn(value, 'input') && !Object.hasOwn(value, 'text')) fail();
+  optional(value, result, 'input', text);
+  optional(value, result, 'text', text);
+  optional(value, result, 'agentMode', (mode) => {
+    if (!['fast', 'reasoning', 'deep'].includes(mode)) fail();
+    return mode;
+  });
+  optional(value, result, 'modelPreference', modelPreference);
+  optional(value, result, 'reasoningPreference', reasoningPreference);
+  optional(value, result, 'approvalMode', durableApprovalMode);
+  const mode = Object.hasOwn(value, 'toolPermissionMode') ? value.toolPermissionMode : 'ask';
+  if (!MODES.includes(mode)) fail();
+  if (!Array.isArray(allowedModes) || !allowedModes.includes(mode)) fail('forbidden');
+  result.toolPermissionMode = mode;
+  optional(value, result, 'attachments', attachments);
+  return result;
+}
+
+function normalize(value, allowedModes) {
+  if (isApprovalCommand(value.type)) return normalizeApprovalCommand(value);
+  const result = { type: value.type };
+  switch (value.type) {
+    case SPARK_OPEN_REQUEST: return result;
+    case 'run_request': return run(value, allowedModes);
+    case 'subscribe_request': return { ...result, requestId: id(value.requestId) };
+    case 'steer_request': return { ...result, requestId: id(value.requestId), steerId: id(value.steerId), text: text(value.text) };
+    case 'tool_approval_response':
+      result.approvalId = approvalId(value.approvalId);
+      result.approved = boolean(value.approved);
+      optional(value, result, 'reason', text);
+      return result;
+    case 'request.events.request':
+      result.requestId = id(value.requestId);
+      optional(value, result, 'afterSeq', (seq) => integer(seq));
+      return result;
+    case 'session.list.request':
+      optional(value, result, 'limit', (limit) => integer(limit, 1, 100));
+      optional(value, result, 'cursor', (cursor) => cursor === null ? null : string(cursor, 4096));
+      return result;
+    case 'session.snapshot.request':
+      result.sessionId = id(value.sessionId);
+      optional(value, result, 'afterMessageId', (cursor) => cursor === null ? null : typeof cursor === 'number' ? integer(cursor) : id(cursor));
+      optional(value, result, 'includeRequests', boolean);
+      return result;
+    case 'session.delete.request':
+    case 'session.messages.clear.request':
+      return { ...result, sessionId: id(value.sessionId) };
+    case 'session.message.delete.request':
+      return { ...result, sessionId: id(value.sessionId),
+        messageId: typeof value.messageId === 'number' ? String(integer(value.messageId)) : id(value.messageId) };
+    case 'attachment.upload.request': return upload(value);
+    case 'attachment.fetch.request': return { ...result, sessionId: id(value.sessionId), attachment: attachment(value.attachment) };
+    default: return fail('unsupported');
+  }
+}
+
+/** Validate client-owned fields only; the relay adds its private correlation ID. */
+export function normalizeClientCommand(body, allowedModes = ['ask']) {
+  // Validate descriptors before reading even the command type.
+  if (!body || typeof body !== 'object' || Array.isArray(body)) fail();
+  const descriptor = Object.getOwnPropertyDescriptor(body, 'type');
+  if (!descriptor || !('value' in descriptor)) fail();
+  const type = string(descriptor.value, 80);
+  if (!Object.hasOwn(FIELDS, type)) {
+    if (/^(?:runtime\.|admin\.|cron\.|schedule\.|session\.(?:delete|messages\.clear|message\.delete)\.)/u.test(type)) fail('forbidden');
+    fail('unsupported');
+  }
+  record(body, ['type', ...FIELDS[type]]);
+  const result = normalize(body, allowedModes);
+  if (Buffer.byteLength(JSON.stringify(result), 'utf8') > MAX_MESSAGE_BYTES) fail();
+  return result;
+}

package/src/protocol/spark-chat-protocol.mjs

@@ -0,0 +1,51 @@
+import { id, string, fail } from './protocol-validation.mjs';
+
+export const SPARK_SESSION_ID = 'spark-companion';
+export const SPARK_CHAT_FEATURE = 'spark_chat_v1';
+export const SPARK_OPEN_REQUEST = 'spark.chat.open.request';
+export const SPARK_OPEN_RESPONSE = 'spark.chat.open.response';
+
+const MODES = new Set(['ask', 'full_access', 'full_plus']);
+const READINESS = new Set(['ready', 'model_required', 'model_unavailable']);
+const ERRORS = new Set(['invalid_spark_chat_request', 'spark_chat_session_unavailable',
+  'spark_chat_model_required', 'spark_chat_model_unavailable', 'spark_chat_permission_mismatch',
+  'spark_chat_unsupported', 'spark_chat_unavailable']);
+
+export function supportsSparkChat(runtime) {
+  if (runtime === undefined) return true;
+  if (runtime.online !== true) return false;
+  return Array.isArray(runtime.features) && runtime.features.includes(SPARK_CHAT_FEATURE);
+}
+
+function isSparkChatCommand(command) {
+  if (command.type === SPARK_OPEN_REQUEST) return true;
+  return command.type === 'run_request' && command.sessionId === SPARK_SESSION_ID;
+}
+
+/** The existing authenticated runtime grant remains the authority ceiling. */
+export function assertSparkChatSupported(command, runtime) {
+  if (!isSparkChatCommand(command)) return;
+  if (!runtime.features.includes(SPARK_CHAT_FEATURE)) fail('spark_chat_unsupported');
+}
+
+function projectSparkChatState(body) {
+  if (body.sessionId !== SPARK_SESSION_ID) fail();
+  if (!MODES.has(body.toolPermissionMode) || !READINESS.has(body.readiness)) fail();
+  const modelProfileId = body.modelProfileId === null ? null : string(body.modelProfileId, 256);
+  if ((modelProfileId === null) !== (body.readiness === 'model_required')) fail();
+  return { sessionId: SPARK_SESSION_ID, modelProfileId,
+    toolPermissionMode: body.toolPermissionMode, readiness: body.readiness };
+}
+
+/** Only chat state crosses the relay; preferences and private diagnostics never do. */
+export function projectSparkOpenResponse(body) {
+  try {
+    if (!body || body.type !== SPARK_OPEN_RESPONSE || typeof body.ok !== 'boolean') return null;
+    const result = { type: SPARK_OPEN_RESPONSE, correlationId: id(body.correlationId), ok: body.ok };
+    if (body.ok) return { ...result, ...projectSparkChatState(body) };
+    if (!ERRORS.has(body.error)) return null;
+    return { ...result, error: body.error };
+  } catch {
+    return null;
+  }
+}

package/src/relay/relay-approvals.mjs

@@ -0,0 +1,86 @@
+import { expectedResponseType } from '../protocol/protocol.mjs';
+import { isApprovalCommand } from '../protocol/approval-protocol.mjs';
+import { isRecord, isRelayId, relayError } from './relay-runtime-registration.mjs';
+import { RelayRequestAdoption } from './relay-request-adoption.mjs';
+
+function validWait(wait) {
+  return isRecord(wait) && isRelayId(wait.generation) && isRelayId(wait.waitId)
+    && Number.isSafeInteger(wait.revision) && wait.revision >= 0;
+}
+
+function validResponse(command, body) {
+  if (!body.ok) return typeof body.error === 'string' && body.error.length <= 256;
+  if (command.type === 'request.approval.decide.request') {
+    return isRecord(body.result) && typeof body.result.accepted === 'boolean'
+      && (body.result.duplicate === undefined || typeof body.result.duplicate === 'boolean')
+      && (body.result.reason === undefined || typeof body.result.reason === 'string');
+  }
+  if (!Array.isArray(body.approvals) || body.approvals.length > 64) return false;
+  const seen = new Set();
+  for (const approval of body.approvals) {
+    const request = approval?.request;
+    if (!isRecord(approval) || !isRecord(request) || request.requestId !== command.requestId) return false;
+    if (typeof request.approvalId !== 'string' || !request.approvalId || request.approvalId.length > 512) return false;
+    if (seen.has(request.approvalId)) return false;
+    seen.add(request.approvalId);
+    if (approval.wait !== undefined && !validWait(approval.wait)) return false;
+  }
+  if (body.lifecycle !== null && !isRecord(body.lifecycle)) return false;
+  if (body.lifecycle?.sessionId !== undefined && body.lifecycle.sessionId !== command.sessionId) return false;
+  if (body.lifecycle?.requestId !== undefined && body.lifecycle.requestId !== command.requestId) return false;
+  if (body.finalState === null) return true;
+  return isRecord(body.finalState) && ['completed', 'failed'].includes(body.finalState.status)
+    && body.approvals.length === 0;
+}
+
+/** An owner-scoped transport view. The runtime alone stores and decides approvals. */
+export class RelayApprovals {
+  constructor({ ownership, requests, correlations, transmit, respond, error,
+    connected, currentRuntime, assertSessionAvailable }) {
+    Object.assign(this, { ownership, requests, correlations, transmit, respond, error });
+    this.adoption = new RelayRequestAdoption({ ownership, requests, correlations, transmit, error,
+      connected, currentRuntime, assertSessionAvailable,
+      recover: (client, runtime, id, command) => this.dispatch(client, runtime, id, command) });
+  }
+
+  owned(client, runtime, command) {
+    if (!this.ownership) throw relayError('approval_access_unavailable');
+    if (!runtime.features.includes('request_approvals_v1')) throw relayError('approvals_unsupported');
+    const owner = this.ownership.get(runtime.runtimeId, command.requestId);
+    if (!owner || owner.subject !== client.subject || owner.sessionId !== command.sessionId) {
+      throw relayError('request_not_owned');
+    }
+    return owner;
+  }
+
+  dispatch(client, runtime, id, command) {
+    if (this.adoption.beginIfUnowned(client, runtime, id, command)) return;
+    this.adoption.assertNoPendingRequest(runtime, command.requestId);
+    const owner = this.owned(client, runtime, command);
+    for (const entry of this.correlations.pending.values()) {
+      if (entry.runtime === runtime && entry.command.requestId === command.requestId
+        && isApprovalCommand(entry.command.type)) throw relayError('approval_request_pending');
+    }
+    let view;
+    const entry = this.correlations.create(client, runtime, id, command, expectedResponseType(command.type), {
+      matches: body => validResponse(command, body),
+      respond: (_entry, body) => {
+        if (!body.ok || body.result?.accepted === false) view.rollback();
+        else if (body.finalState) this.requests.markTerminal(view.record);
+        this.respond(client, runtime, id, body);
+      },
+      unknown: () => {
+        view.rollback();
+        this.error(client, runtime, id, 'outcome_unknown');
+      },
+      // A sent decision can still take effect after its client closes. Keep the
+      // mutation guard until its reply/deadline, but disconnect removes the view.
+      retainOnClientDisconnect: true,
+    });
+    try { view = this.requests.restore(client, runtime, owner); }
+    catch (error) { this.correlations.remove(entry); throw error; }
+    if (!this.transmit(runtime.peer, { ...command, correlationId: entry.correlationId })) {
+      this.correlations.fail(entry);
+    }
+  }
+}

package/src/relay/relay-client-admission.mjs

@@ -0,0 +1,40 @@
+import { isRecord, isRelayId, relayError } from './relay-runtime-registration.mjs';
+
+const MAX_COMMANDS = 512;
+const COMMANDS_PER_MINUTE = 60;
+
+export function createRelayClient(peer, identity, now) {
+  if (!isRecord(identity) || typeof identity.subject !== 'string' || identity.subject.length > 320 || !identity.subject) {
+    throw relayError('invalid_client_identity');
+  }
+  if (typeof identity.sessionId !== 'string' || !identity.sessionId || identity.sessionId.length > 256) {
+    throw relayError('invalid_client_identity');
+  }
+  if (!Array.isArray(identity.allowedRuntimeIds) || identity.allowedRuntimeIds.length > 32) {
+    throw relayError('invalid_client_identity');
+  }
+  if (identity.allowedRuntimeIds.some(id => !isRelayId(id))) throw relayError('invalid_client_identity');
+  return {
+    peer, subject: identity.subject, sessionId: identity.sessionId,
+    allowedRuntimeIds: new Set(identity.allowedRuntimeIds), commands: new Set(),
+    rateStartedAt: now, rateCount: 0,
+  };
+}
+
+export function admitRelayCommand(client, message, now) {
+  // Charge failed commands too. Authentication and IP rate limits are transport-owned.
+  if (now - client.rateStartedAt >= 60_000) {
+    client.rateStartedAt = now;
+    client.rateCount = 0;
+  }
+  client.rateCount += 1;
+  if (client.rateCount > COMMANDS_PER_MINUTE) throw relayError('rate_limited');
+  if (!isRecord(message) || !isRelayId(message.id) || !isRelayId(message.runtimeId)) {
+    throw relayError('invalid_command_envelope');
+  }
+  if (!client.allowedRuntimeIds.has(message.runtimeId)) throw relayError('runtime_forbidden');
+  if (client.commands.has(message.id)) throw relayError('duplicate_command');
+  if (client.commands.size >= MAX_COMMANDS) throw relayError('command_capacity');
+  // IDs are not evicted while a connection is alive; a retry never re-dispatches.
+  client.commands.add(message.id);
+}

package/src/relay/relay-correlations.mjs

@@ -0,0 +1,101 @@
+import { randomUUID } from 'node:crypto';
+import { isRecord, relayError } from './relay-runtime-registration.mjs';
+import { isApprovalCommand } from '../protocol/approval-protocol.mjs';
+import { SPARK_OPEN_REQUEST, projectSparkOpenResponse } from '../protocol/spark-chat-protocol.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 === SPARK_OPEN_REQUEST) return projectSparkOpenResponse(body) !== null;
+  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' || isApprovalCommand(command.type))
+    && 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 entry.lifecycle.matches?.(body) ?? 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);
+    const response = entry.command.type === SPARK_OPEN_REQUEST ? projectSparkOpenResponse(body) : body;
+    (entry.lifecycle.respond ?? this.respond)(entry, response);
+    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 };
+}