@abot-ai/socket 0.0.0-stage → 0.2.0

package/src/relay/relay-request-adoption.mjs

@@ -0,0 +1,97 @@
+import { isRecord, relayError } from './relay-runtime-registration.mjs';
+
+const REQUEST_STATUSES = new Set(['streaming', 'awaiting_approval', 'completed', 'failed']);
+const requestKey = (runtime, requestId) => JSON.stringify([runtime.generation, requestId]);
+const isTerminalRequest = request => ['completed', 'failed'].includes(request.status);
+
+function confirmedSnapshotRequest(command, body) {
+  if (!body.ok) throw relayError('request_scope_unverified');
+  if (!Array.isArray(body.requests) || body.nextCursor !== null) throw relayError('request_scope_unverified');
+  const matches = body.requests.filter(request => isRecord(request) && request.requestId === command.requestId);
+  if (matches.length !== 1) throw relayError('request_scope_unverified');
+  const request = matches[0];
+  if (request.sessionId !== command.sessionId) throw relayError('request_scope_unverified');
+  if (!REQUEST_STATUSES.has(request.status)) throw relayError('request_scope_unverified');
+  return request;
+}
+
+/** First contact with existing computer work needs canonical proof, never a client ownership claim. */
+export class RelayRequestAdoption {
+  constructor({ ownership, requests, correlations, transmit, connected, currentRuntime,
+    assertSessionAvailable, recover, error }) {
+    Object.assign(this, { ownership, requests, correlations, transmit, connected, currentRuntime,
+      assertSessionAvailable, recover, error });
+    this.pending = new Map();
+  }
+
+  assertNoPendingRequest(runtime, requestId) {
+    if (this.pending.has(requestKey(runtime, requestId))) throw relayError('approval_request_pending');
+  }
+
+  assertNoPendingSession(runtime, sessionId) {
+    for (const operation of this.pending.values()) {
+      if (operation.runtime === runtime && operation.command.sessionId === sessionId) {
+        throw relayError('session_busy');
+      }
+    }
+  }
+
+  assertCurrentPrincipal(client, runtime) {
+    if (!this.connected(client)) throw relayError('approval_access_unavailable');
+    if (!this.currentRuntime(runtime)) throw relayError('runtime_offline');
+    if (!client.allowedRuntimeIds.has(runtime.runtimeId)) throw relayError('runtime_forbidden');
+    if (this.ownership?.isOwnerSubject?.(client.subject) !== true) throw relayError('request_not_owned');
+    if (typeof this.ownership.adopt !== 'function') throw relayError('approval_access_unavailable');
+  }
+
+  assertCompatibleBinding(client, runtime, command) {
+    const binding = this.requests.bindings.get(JSON.stringify([runtime.runtimeId, command.requestId]));
+    if (!binding) return;
+    if (!binding.durable || binding.subject !== client.subject || binding.sessionId !== command.sessionId) {
+      throw relayError('request_not_owned');
+    }
+  }
+
+  beginIfUnowned(client, runtime, id, command) {
+    if (command.type !== 'request.approvals.request') return false;
+    if (!this.ownership || !runtime.features.includes('request_approvals_v1')) return false;
+    if (this.ownership.get(runtime.runtimeId, command.requestId)) return false;
+    this.assertCurrentPrincipal(client, runtime);
+    this.assertNoPendingRequest(runtime, command.requestId);
+    this.assertCompatibleBinding(client, runtime, command);
+    this.assertSessionAvailable(runtime, command.sessionId);
+    const operation = { client, runtime, id, command, key: requestKey(runtime, command.requestId) };
+    const snapshot = { type: 'session.snapshot.request', sessionId: command.sessionId, includeRequests: true };
+    const entry = this.correlations.create(client, runtime, id, snapshot, 'session.snapshot.response', {
+      respond: (_entry, body) => this.afterSnapshot(operation, body),
+      unknown: () => this.error(client, runtime, id, 'outcome_unknown'),
+      removed: () => {
+        if (this.pending.get(operation.key) === operation) this.pending.delete(operation.key);
+      },
+    });
+    this.pending.set(operation.key, operation);
+    if (!this.transmit(runtime.peer, { ...snapshot, correlationId: entry.correlationId })) {
+      this.correlations.fail(entry);
+    }
+    return true;
+  }
+
+  afterSnapshot(operation, body) {
+    const { client, runtime, id, command } = operation;
+    try {
+      this.assertCurrentPrincipal(client, runtime);
+      this.assertSessionAvailable(runtime, command.sessionId);
+      this.assertCompatibleBinding(client, runtime, command);
+      const canonical = confirmedSnapshotRequest(command, body);
+      const terminal = isTerminalRequest(canonical);
+      const binding = this.requests.bindings.get(JSON.stringify([runtime.runtimeId, command.requestId]));
+      this.requests.assertCapacity(binding, !terminal);
+      this.ownership.adopt({ subject: client.subject, deviceId: client.sessionId,
+        runtimeId: runtime.runtimeId, sessionId: command.sessionId, requestId: command.requestId }, terminal);
+      // Normal recovery binds before receiving approval events and retains the runtime's decision checks.
+      this.recover(client, runtime, id, command);
+    } catch (error) {
+      this.error(client, runtime, id, error.code ?? 'approval_access_unavailable');
+    }
+  }
+}

package/src/relay/relay-requests.mjs

@@ -0,0 +1,211 @@
+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, ownership, observe = () => {} }) {
+    this.now = now;
+    this.event = event;
+    this.unknown = unknown;
+    this.observe = observe;
+    this.ownership = ownership;
+    this.bindings = new Map();
+  }
+
+  create(client, runtime, command) {
+    const key = keyFor(runtime.runtimeId, command.requestId);
+    if (this.bindings.has(key) || this.ownership?.get(runtime.runtimeId, command.requestId)) {
+      throw relayError('request_id_conflict');
+    }
+    this.assertCapacity();
+    const durable = command.approvalMode === 'durable_v1';
+    if (durable) {
+      if (!this.ownership) throw relayError('approval_access_unavailable');
+      if (!runtime.features.includes('request_approvals_v1')) throw relayError('approvals_unsupported');
+      // This commit precedes transport: an uncertain send must never permit a replayed run.
+      this.ownership.create({ subject: client.subject, deviceId: client.sessionId,
+        runtimeId: runtime.runtimeId, sessionId: command.sessionId, requestId: command.requestId });
+    }
+    const record = { key, subject: client.subject, deviceId: client.sessionId, runtime, requestId: command.requestId,
+      sessionId: command.sessionId, state: 'active', subscribers: new Set([client]), durable,
+      expiresAt: durable ? Infinity : this.now() + BINDING_TTL_MS,
+      version: 0, approvals: new Map(), steering: new Set() };
+    this.bindings.set(key, record);
+    return record;
+  }
+
+  assertCapacity(existing, active = true) {
+    if (!existing && this.bindings.size >= MAX_BINDINGS) throw relayError('request_capacity');
+    const activeCount = [...this.bindings.values()].filter(record => record.state === 'active').length;
+    if (active && existing?.state !== 'active' && activeCount >= MAX_ACTIVE) {
+      throw relayError('active_request_capacity');
+    }
+  }
+
+  /** Restore a delivery view, not authority to execute or approve the saved request. */
+  restore(client, runtime, owner) {
+    const key = keyFor(runtime.runtimeId, owner.requestId);
+    const previous = this.bindings.get(key);
+    if (previous && (!previous.durable || previous.subject !== owner.subject
+      || previous.sessionId !== owner.sessionId)) throw relayError('request_not_owned');
+    const active = owner.status !== 'terminal';
+    const reusable = previous?.runtime === runtime && previous.state === (active ? 'active' : 'terminal');
+    this.assertCapacity(previous, active);
+    const record = reusable ? previous : { key, subject: owner.subject, deviceId: owner.deviceId,
+      runtime, sessionId: owner.sessionId, requestId: owner.requestId, durable: true,
+      state: active ? 'active' : 'terminal', expiresAt: active ? Infinity : owner.terminalAt + BINDING_TTL_MS,
+      version: 0, subscribers: new Set(previous?.subscribers), approvals: new Map(), steering: new Set() };
+    const wasSubscribed = record.subscribers.has(client);
+    const version = record.version;
+    record.subscribers.add(client);
+    this.bindings.set(key, record);
+    return { record, rollback: () => {
+      if (this.bindings.get(key) !== record || record.version !== version) return;
+      if (!reusable) {
+        if (!wasSubscribed) record.subscribers.delete(client);
+        if (previous) {
+          previous.subscribers = new Set(record.subscribers);
+          this.bindings.set(key, previous);
+        }
+        else this.bindings.delete(key);
+      } else if (!wasSubscribed) record.subscribers.delete(client);
+    } };
+  }
+
+  markTerminal(record) {
+    if (record.durable) this.ownership.markTerminal(record.runtime.runtimeId, record.requestId);
+    record.state = 'terminal';
+    record.expiresAt = this.now() + BINDING_TTL_MS;
+    record.version += 1;
+    this.invalidateApprovals(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.durable || 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 (!record.durable && 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') {
+      this.markTerminal(record);
+    }
+    record.version += 1;
+    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 (record.durable) return body.sessionId === record.sessionId;
+    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 = record.durable ? Infinity : 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,122 @@
+import { expectedResponseType } from '../protocol/protocol.mjs';
+import { relayError } from './relay-runtime-registration.mjs';
+import { isApprovalCommand } from '../protocol/approval-protocol.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, ownership, transmit, connected, error, respond }) {
+    Object.assign(this, { now, correlations, requests, ownership, 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.sessionId !== sessionId) continue;
+      if (record.durable) {
+        if (record.runtime.runtimeId !== runtime.runtimeId) continue;
+        // Unknown durable work needs individual canonical proof below; it is
+        // never treated as completed merely because this relay restarted.
+        if (record.state === 'unknown') continue;
+      } else if (record.runtime !== runtime) 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' || isApprovalCommand(entry.command.type))) {
+        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.reconcileOwnership(operation, body.requests);
+      this.send(operation, operation.command, result => {
+        const wholeSessionRemoved = result.ok && (
+          (operation.command.type === 'session.delete.request' && result.deleted === true)
+          || (operation.command.type === 'session.messages.clear.request' && result.cleared === true));
+        if (wholeSessionRemoved) this.ownership?.retireSession(operation.runtime.runtimeId, operation.command.sessionId);
+        this.respond(operation, result);
+      });
+    } catch (error) {
+      this.error(operation, error.code ?? 'session_state_unavailable');
+    }
+  }
+
+  reconcileOwnership(operation, canonical) {
+    const runtimeId = operation.runtime.runtimeId;
+    const owners = this.ownership?.listSession(runtimeId, operation.command.sessionId) ?? [];
+    const open = owners.filter(owner => owner.status === 'open');
+    // Missing requests and partial histories are not evidence of completion.
+    for (const owner of open) {
+      if (!canonical.some(request => request.requestId === owner.requestId
+        && request.sessionId === owner.sessionId && ['completed', 'failed'].includes(request.status))) {
+        throw relayError('session_busy');
+      }
+    }
+    for (const owner of open) {
+      this.ownership.markTerminal(runtimeId, owner.requestId);
+      const view = this.requests.bindings.get(JSON.stringify([runtimeId, owner.requestId]));
+      if (view?.durable && view.sessionId === owner.sessionId) this.requests.markTerminal(view);
+    }
+  }
+
+  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);
+    }
+  }
+}