@abot-ai/socket 0.0.0-stage → 0.1.0

package/src/notifications/notification-service.mjs

@@ -0,0 +1,147 @@
+import { NotificationStore } from './notification-store.mjs';
+import { NotificationOutbox } from './notification-outbox.mjs';
+import { closesApprovalNotifications, projectNotificationEvent } from './notification-projection.mjs';
+import { notificationInputError } from './notification-input.mjs';
+
+const PRESENCE_MS = 45_000;
+
+/** Notification lifecycle is independent of a selected runtime or a live mobile socket. */
+export class NotificationService {
+  constructor({ database, delivery, now = Date.now, onChanged = () => {} }) {
+    this.store = new NotificationStore({ database, now });
+    this.outbox = new NotificationOutbox({ database, now });
+    this.delivery = delivery;
+    this.now = now;
+    this.onChanged = onChanged;
+    this.presence = new Map();
+    this.closed = false;
+    this.pending = null;
+    this.active = null;
+  }
+
+  changed(deviceId) {
+    try { this.onChanged(deviceId); } catch { /* Invalidation is best effort; HTTP is canonical. */ }
+  }
+
+  observe(identity, body) {
+    let changed = false;
+    if (closesApprovalNotifications(body)) {
+      changed = this.store.closeApprovals(identity, body.type === 'event' ? body.approvalId : undefined);
+      if (this.active?.entry.notification.kind === 'approval_required' &&
+        this.active.entry.deviceId === identity.deviceId &&
+        this.active.entry.notification.runtimeId === identity.runtimeId &&
+        this.active.entry.notification.requestId === identity.requestId) this.active.controller.abort();
+    }
+    const projected = projectNotificationEvent(identity, body, this.now());
+    if (projected) {
+      const registration = this.store.registration(identity.deviceId);
+      const queue = this.delivery.configured && registration?.provider === this.delivery.mode;
+      const item = this.store.record(projected, queue);
+      if (item && queue) this.store.previews.attach(item, body.output);
+      changed = Boolean(item) || changed;
+    }
+    if (changed) this.changed(identity.deviceId);
+  }
+
+  list(deviceId, options) {
+    const registration = this.store.registration(deviceId);
+    return { version: 1, ...this.store.list(deviceId, options),
+      delivery: { mode: this.delivery.mode, configured: this.delivery.configured },
+      registration: { enabled: this.delivery.configured && registration?.provider === this.delivery.mode },
+      preview: this.store.previews.status(deviceId) };
+  }
+
+  markRead(deviceId, ids) {
+    if (this.active?.entry.deviceId === deviceId && ids.includes(this.active.entry.notification.id)) {
+      this.active.controller.abort();
+    }
+    if (this.store.markRead(deviceId, ids)) this.changed(deviceId);
+  }
+
+  updatePresence(deviceId, presence) {
+    if (!presence.foreground) { this.presence.delete(deviceId); return; }
+    this.presence.set(deviceId, { ...presence, expiresAt: this.now() + PRESENCE_MS });
+    // Advisory only: iOS may suspend before a background update is delivered.
+    // Only an explicit read acknowledgement can consume an unseen notification.
+  }
+
+  register(deviceId, registration) {
+    if (!this.delivery.configured || registration.provider !== this.delivery.mode) {
+      throw notificationInputError('push_unavailable', 409);
+    }
+    if (this.active?.entry.deviceId === deviceId) this.active.controller.abort();
+    if (!this.store.register(deviceId, registration)) throw notificationInputError('unauthorized', 401);
+  }
+
+  enablePreview(deviceId, key) {
+    const registration = this.store.registration(deviceId);
+    if (!this.delivery.configured || registration?.provider !== this.delivery.mode) {
+      throw notificationInputError('push_unavailable', 409);
+    }
+    if (this.active?.entry.deviceId === deviceId) this.active.controller.abort();
+    if (!this.store.previews.enable(deviceId, key)) throw notificationInputError('unauthorized', 401);
+  }
+
+  disablePreview(deviceId) {
+    if (this.active?.entry.deviceId === deviceId) this.active.controller.abort();
+    this.store.previews.disable(deviceId);
+  }
+
+  unregister(deviceId) {
+    if (this.active?.entry.deviceId === deviceId) this.active.controller.abort();
+    this.store.unregister(deviceId);
+  }
+
+  revoke(deviceId) {
+    if (this.active?.entry.deviceId === deviceId) this.active.controller.abort();
+    this.presence.delete(deviceId);
+    this.store.forgetDevice(deviceId);
+  }
+
+  start() {
+    if (this.timer || this.closed) return;
+    this.timer = setInterval(() => { void this.tick(); }, 1_000);
+    this.timer.unref();
+  }
+
+  tick() {
+    if (this.closed) return Promise.resolve();
+    if (this.pending) return this.pending;
+    this.pending = this.drain().catch(() => { /* Durable entries remain for a later bounded attempt. */ })
+      .finally(() => { this.pending = null; });
+    return this.pending;
+  }
+
+  async drain() {
+    this.store.prune();
+    for (const [deviceId, presence] of this.presence) {
+      if (presence.expiresAt <= this.now()) this.presence.delete(deviceId);
+    }
+    if (!this.delivery.configured) return;
+    for (let index = 0; index < 10 && !this.closed; index += 1) {
+      const entry = this.outbox.claim(this.delivery.mode);
+      if (!entry) return;
+      if (!this.outbox.canDeliver(entry)) continue;
+      const controller = new AbortController();
+      this.active = { entry, controller };
+      let result;
+      try {
+        result = await this.delivery.send({ registration: entry.registration, notification: entry.notification,
+          badge: this.store.counts(entry.deviceId).unreadCount }, controller.signal);
+      } catch { result = { status: 'retry' }; }
+      this.active = null;
+      if (controller.signal.aborted) { this.outbox.cancel(entry); continue; }
+      const status = ['delivered', 'invalid', 'discarded', 'retry'].includes(result?.status) ? result.status : 'retry';
+      if (status === 'invalid') this.store.unregister(entry.deviceId, entry.registration);
+      this.outbox.finish(entry, status);
+    }
+  }
+
+  async close() {
+    this.closed = true;
+    clearInterval(this.timer);
+    this.active?.controller.abort();
+    await this.pending;
+    this.presence.clear();
+  }
+}

package/src/notifications/notification-store.mjs

@@ -0,0 +1,132 @@
+import { randomUUID } from 'node:crypto';
+import { notificationCursor } from './notification-input.mjs';
+import { NotificationPreviewStore } from './notification-preview-store.mjs';
+
+const MAX_ITEMS_PER_DEVICE = 500;
+const SELECT_ITEM = `id, runtime_id AS runtimeId, session_id AS sessionId,
+  request_id AS requestId, kind, created_at AS createdAt, read_at AS readAt, expires_at AS expiresAt`;
+
+export class NotificationStore {
+  constructor({ database, now = Date.now }) {
+    this.database = database; this.now = now;
+    this.previews = new NotificationPreviewStore({ database, now });
+  }
+
+  hasDevice(deviceId) {
+    return Boolean(this.database.prepare('SELECT id FROM devices WHERE id = ? AND expires_at > ?')
+      .get(deviceId, this.now()));
+  }
+
+  record(event, queueDelivery) {
+    return this.database.transaction(() => {
+      const device = this.database.prepare('SELECT expires_at FROM devices WHERE id = ? AND expires_at > ?')
+        .get(event.deviceId, this.now());
+      if (!device) return null;
+      const item = { id: randomUUID(), ...event, readAt: null,
+        expiresAt: Math.min(event.expiresAt, device.expires_at) };
+      const added = this.database.prepare(`INSERT OR IGNORE INTO notifications
+        (id, device_id, runtime_id, session_id, request_id, kind, approval_id, created_at, read_at, expires_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(item.id, item.deviceId, item.runtimeId,
+        item.sessionId, item.requestId, item.kind, item.approvalId, item.createdAt, item.readAt, item.expiresAt);
+      if (!added.changes) return null;
+      if (queueDelivery) {
+        this.database.prepare('INSERT INTO notification_outbox(notification_id, next_at) VALUES (?, ?)')
+          .run(item.id, this.now());
+      }
+      this.database.prepare(`DELETE FROM notifications WHERE device_id = ? AND id IN (
+        SELECT id FROM notifications WHERE device_id = ? ORDER BY created_at DESC, id DESC LIMIT -1 OFFSET ?)`)
+        .run(item.deviceId, item.deviceId, MAX_ITEMS_PER_DEVICE);
+      return item;
+    });
+  }
+
+  list(deviceId, { limit = 50, before = null } = {}) {
+    this.prune();
+    const condition = before ? 'AND (created_at < ? OR (created_at = ? AND id < ?))' : '';
+    const parameters = before ? [deviceId, before.createdAt, before.createdAt, before.id, limit + 1] : [deviceId, limit + 1];
+    const rows = this.database.prepare(`SELECT ${SELECT_ITEM} FROM notifications WHERE device_id = ?
+      ${condition} ORDER BY created_at DESC, id DESC LIMIT ?`).all(...parameters);
+    const items = rows.slice(0, limit).map(row => ({ ...row }));
+    const counts = this.counts(deviceId);
+    return { items, nextCursor: rows.length > limit ? notificationCursor(items.at(-1)) : null, ...counts };
+  }
+
+  counts(deviceId) {
+    const rows = this.database.prepare(`SELECT runtime_id, session_id, COUNT(*) AS count FROM notifications
+      WHERE device_id = ? AND read_at IS NULL AND expires_at > ? GROUP BY runtime_id, session_id`).all(deviceId, this.now());
+    const unreadByRuntime = Object.create(null);
+    const unreadBySession = Object.create(null);
+    let unreadCount = 0;
+    for (const row of rows) {
+      unreadCount += row.count;
+      unreadByRuntime[row.runtime_id] = (unreadByRuntime[row.runtime_id] ?? 0) + row.count;
+      unreadBySession[row.runtime_id] ??= Object.create(null);
+      unreadBySession[row.runtime_id][row.session_id] = row.count;
+    }
+    return { unreadCount, unreadByRuntime, unreadBySession };
+  }
+
+  markRead(deviceId, ids) {
+    return this.database.transaction(() => {
+      const update = this.database.prepare('UPDATE notifications SET read_at = ? WHERE device_id = ? AND id = ? AND read_at IS NULL');
+      let changes = 0;
+      for (const id of ids) changes += update.run(this.now(), deviceId, id).changes;
+      this.removeReadDeliveries();
+      return changes > 0;
+    });
+  }
+
+  closeApprovals(identity, approvalId) {
+    const conditions = approvalId ? 'AND approval_id = ?' : '';
+    const params = [this.now(), identity.deviceId, identity.runtimeId, identity.requestId];
+    if (approvalId) params.push(approvalId);
+    const changed = this.database.prepare(`UPDATE notifications SET read_at = COALESCE(read_at, ?)
+      WHERE device_id = ? AND runtime_id = ? AND request_id = ? AND kind = 'approval_required' ${conditions}`)
+      .run(...params).changes;
+    this.removeReadDeliveries();
+    return changed > 0;
+  }
+
+  registration(deviceId) {
+    const row = this.database.prepare('SELECT registration FROM notification_registrations WHERE device_id = ?').get(deviceId);
+    return row ? JSON.parse(row.registration) : null;
+  }
+
+  register(deviceId, registration) {
+    if (!this.hasDevice(deviceId)) return false;
+    this.database.prepare(`INSERT INTO notification_registrations(device_id, provider, registration, updated_at)
+      VALUES (?, ?, ?, ?) ON CONFLICT(device_id) DO UPDATE SET provider = excluded.provider,
+      registration = excluded.registration, updated_at = excluded.updated_at`)
+      .run(deviceId, registration.provider, JSON.stringify(registration), this.now());
+    return true;
+  }
+
+  unregister(deviceId, expectedRegistration) {
+    this.database.transaction(() => {
+      if (expectedRegistration && JSON.stringify(this.registration(deviceId)) !== JSON.stringify(expectedRegistration)) return;
+      this.previews.removeKey(deviceId);
+      this.database.prepare('DELETE FROM notification_registrations WHERE device_id = ?').run(deviceId);
+      this.database.prepare(`DELETE FROM notification_outbox WHERE notification_id IN
+        (SELECT id FROM notifications WHERE device_id = ?)` ).run(deviceId);
+    });
+  }
+
+  removeReadDeliveries() {
+    this.database.prepare(`DELETE FROM notification_outbox WHERE notification_id IN
+      (SELECT id FROM notifications WHERE read_at IS NOT NULL)` ).run();
+  }
+
+  prune() {
+    this.database.prepare('DELETE FROM notifications WHERE expires_at <= ?').run(this.now());
+    this.database.prepare('DELETE FROM notifications WHERE NOT EXISTS (SELECT 1 FROM devices WHERE devices.id = notifications.device_id)').run();
+    this.database.prepare('DELETE FROM notification_registrations WHERE NOT EXISTS (SELECT 1 FROM devices WHERE devices.id = notification_registrations.device_id)').run();
+    this.database.prepare('DELETE FROM notification_registrations WHERE device_id IN (SELECT id FROM devices WHERE expires_at <= ?)').run(this.now());
+    this.database.prepare('DELETE FROM notifications WHERE device_id IN (SELECT id FROM devices WHERE expires_at <= ?)').run(this.now());
+    this.previews.prune();
+  }
+
+  forgetDevice(deviceId) {
+    this.unregister(deviceId);
+    this.database.prepare('DELETE FROM notifications WHERE device_id = ?').run(deviceId);
+  }
+}

package/src/pairing/pairing-qr-payload.mjs

@@ -0,0 +1,32 @@
+/** Public format for an operator-issued, short-lived pairing QR. Never a URL. */
+export const PAIRING_QR_TYPE = 'abot-pairing';
+export const PAIRING_QR_VERSION = 1;
+
+function hasCanonicalPairingOrigin(value) {
+  if (typeof value !== 'string' || value.length > 2048) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === 'https:' && url.origin === value;
+  } catch { return false; }
+}
+
+function hasPairingCredentials(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  if (!hasCanonicalPairingOrigin(value.serverUrl)) return false;
+  if (typeof value.pairingId !== 'string' || !/^[A-Za-z0-9_-]{32}$/.test(value.pairingId)) return false;
+  if (typeof value.code !== 'string' || !/^\d{6}$/.test(value.code)) return false;
+  return Number.isSafeInteger(value.expiresAt) && value.expiresAt > 0;
+}
+
+export function pairingQrPayload(pairing) {
+  if (!hasPairingCredentials(pairing)) throw new Error('Invalid pairing QR details');
+  // Explicit selection keeps runtime tokens and future operator-only fields out.
+  return JSON.stringify({
+    type: PAIRING_QR_TYPE,
+    version: PAIRING_QR_VERSION,
+    serverUrl: pairing.serverUrl,
+    pairingId: pairing.pairingId,
+    code: pairing.code,
+    expiresAt: pairing.expiresAt,
+  });
+}

package/src/pairing/pairing-qr.mjs

@@ -0,0 +1,42 @@
+import qrcode from 'qrcode-generator';
+import { pairingQrPayload } from './pairing-qr-payload.mjs';
+
+const QUIET_MODULES = 4;
+const BLACK_ON_WHITE = '\u001b[30;47m';
+const RESET = '\u001b[0m';
+
+function fitsTerminal(width, columns) {
+  // Leave one column free: some terminals wrap immediately at the last column.
+  return Number.isInteger(columns) && columns > width;
+}
+
+function isDarkModule(qr, row, column) {
+  const size = qr.getModuleCount();
+  if (row < 0 || column < 0 || row >= size || column >= size) return false;
+  return qr.isDark(row, column);
+}
+
+function halfBlock(top, bottom) {
+  if (top && bottom) return '█';
+  if (top) return '▀';
+  if (bottom) return '▄';
+  return ' ';
+}
+
+/** Fixed black/white terminal QR, independent of the operator's terminal theme. */
+export function renderPairingQr(pairing, { columns = 80 } = {}) {
+  const qr = qrcode(0, 'M');
+  qr.addData(pairingQrPayload(pairing), 'Byte');
+  qr.make();
+  const size = qr.getModuleCount();
+  if (!fitsTerminal(size + QUIET_MODULES * 2, columns)) return null;
+  const lines = [];
+  for (let row = -QUIET_MODULES; row < size + QUIET_MODULES; row += 2) {
+    let line = '';
+    for (let column = -QUIET_MODULES; column < size + QUIET_MODULES; column++) {
+      line += halfBlock(isDarkModule(qr, row, column), isDarkModule(qr, row + 1, column));
+    }
+    lines.push(`${BLACK_ON_WHITE}${line}${RESET}`);
+  }
+  return lines.join('\n');
+}

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,110 @@
+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';
+
+export { MAX_MESSAGE_BYTES, MAX_ATTACHMENT_BYTES, MAX_TEXT_BYTES } from './protocol-validation.mjs';
+
+const FIELDS = Object.freeze({
+  run_request: ['requestId', 'sessionId', 'input', 'text', 'agentMode', 'modelPreference', 'reasoningPreference', 'toolPermissionMode', 'attachments'],
+  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({
+  '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);
+  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) {
+  const result = { type: value.type };
+  switch (value.type) {
+    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/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);
+}