enigma-memory 0.1.18 → 0.1.22

package/packages/inference-runtime/src/browser.js

@@ -0,0 +1,401 @@
+import dns from 'node:dns/promises';
+import net from 'node:net';
+import { createPublicKey, randomUUID, verify as verifySignature } from 'node:crypto';
+
+export const ENIGMA_BROWSER_SESSION_SCHEMA = 'enigma.browser_session.v1';
+const TERMINAL = new Set(['burned', 'failed']);
+const CONTROL_ACTIONS = new Set(['reload', 'back', 'forward', 'click', 'type', 'keypress', 'scroll']);
+
+function requiredString(value, field, maxLength = 16_000) {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${field} must be a non-empty string`);
+  const normalized = value.trim();
+  if (normalized.length > maxLength) throw new TypeError(`${field} exceeds ${maxLength} characters`);
+  return normalized;
+}
+
+function boundedInteger(value, field, minimum, maximum, fallback) {
+  const candidate = value === undefined ? fallback : value;
+  if (!Number.isInteger(candidate) || candidate < minimum || candidate > maximum) {
+    throw new TypeError(`${field} must be an integer from ${minimum} to ${maximum}`);
+  }
+  return candidate;
+}
+
+function isDeniedIp(address) {
+  const normalized = String(address).toLowerCase().split('%')[0];
+  if (net.isIPv4(normalized)) {
+    const [a, b, c] = normalized.split('.').map(Number);
+    return a === 0 || a === 10 || a === 127 || (a === 100 && b >= 64 && b <= 127)
+      || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31)
+      || (a === 192 && b === 0) || (a === 192 && b === 168)
+      || (a === 198 && (b === 18 || b === 19)) || (a === 198 && b === 51 && c === 100)
+      || (a === 203 && b === 0 && c === 113) || a >= 224;
+  }
+  if (net.isIPv6(normalized)) {
+    return normalized === '::' || normalized === '::1' || normalized.startsWith('fc') || normalized.startsWith('fd')
+      || normalized.startsWith('fe8') || normalized.startsWith('fe9') || normalized.startsWith('fea')
+      || normalized.startsWith('feb') || normalized.startsWith('ff') || normalized.startsWith('2001:db8:')
+      || normalized.startsWith('2001:10:');
+  }
+  return true;
+}
+
+export async function assertPublicNavigationUrl(value, lookup = dns.lookup) {
+  const url = new URL(requiredString(value, 'url', 8_192));
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') throw new TypeError('browser navigation only supports HTTP and HTTPS');
+  if (url.username || url.password) throw new TypeError('browser navigation URL must not contain credentials');
+  const hostname = url.hostname.toLowerCase();
+  if (hostname === 'localhost' || hostname.endsWith('.localhost') || hostname.endsWith('.local') || hostname.endsWith('.internal')) {
+    throw new Error('private or local browser destination blocked');
+  }
+  if (net.isIP(hostname)) {
+    if (isDeniedIp(hostname)) throw new Error('private or special-use browser destination blocked');
+  } else {
+    const answers = await lookup(hostname, { all: true, verbatim: true });
+    if (!answers.length || answers.some(({ address }) => isDeniedIp(address))) {
+      throw new Error('browser destination resolves to a private or special-use address');
+    }
+  }
+  return url.toString();
+}
+function normalizeViewerOrigin(value) {
+  const url = new URL(requiredString(value, 'browser viewer origin', 4_096));
+  const localHttp = url.protocol === 'http:' && ['127.0.0.1', 'localhost'].includes(url.hostname);
+  if (url.protocol !== 'https:' && !localHttp) throw new TypeError('browser viewer origin must use HTTPS outside localhost');
+  if (url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+    throw new TypeError('browser viewer origin must contain only scheme, host, and port');
+  }
+  return url.origin;
+}
+
+function validateViewerUrl(value, expectedOrigin) {
+  if (!value) return null;
+  const url = new URL(requiredString(value, 'browser stream URL', 8_192));
+  if (url.origin !== expectedOrigin) throw new Error('browser broker returned a viewer URL outside the configured origin');
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['127.0.0.1', 'localhost'].includes(url.hostname))) {
+    throw new Error('browser stream URL must use HTTPS outside localhost');
+  }
+  if (url.username || url.password) throw new Error('browser stream URL must not use URL authority credentials');
+  return url.toString();
+}
+
+
+function normalizeDisplay(input = {}) {
+  const profile = input.profile || 'sharp';
+  const presets = {
+    efficient: { profile: 'efficient', width: 1440, height: 810, fps: 30 },
+    sharp: { profile: 'sharp', width: 1920, height: 1080, fps: 30 },
+    ultra: { profile: 'ultra', width: 2560, height: 1440, fps: 24 },
+  };
+  if (presets[profile] && input.width === undefined && input.height === undefined && input.fps === undefined) return presets[profile];
+  const display = {
+    profile: presets[profile] ? profile : 'custom',
+    width: boundedInteger(input.width, 'display.width', 720, 2560, 1920),
+    height: boundedInteger(input.height, 'display.height', 600, 2160, 1080),
+    fps: boundedInteger(input.fps, 'display.fps', 1, 60, 30),
+  };
+  if (display.width * display.height > 4_100_000 || display.width / display.height < 0.5 || display.width / display.height > 2.75) {
+    throw new TypeError('display dimensions exceed the private browser pixel or aspect-ratio limit');
+  }
+  return display;
+}
+
+function normalizeTabs(value) {
+  if (!Array.isArray(value)) return [];
+  return value.slice(0, 5).map((tab) => ({
+    id: requiredString(tab.id, 'tab id', 512),
+    title: typeof tab.title === 'string' ? tab.title.slice(0, 512) : '',
+    url: typeof tab.url === 'string' ? tab.url.slice(0, 8_192) : 'about:blank',
+    zoom: Number.isFinite(tab.zoom) ? tab.zoom : 1,
+  }));
+}
+const REQUIRED_EGRESS_CONTROLS = Object.freeze([
+  'dnsRebindingProtected',
+  'redirectsRevalidated',
+  'privateCidrsBlocked',
+  'metadataEndpointsBlocked',
+  'quicBlocked',
+  'nonProxiedWebRtcBlocked',
+  'interactiveNavigationCovered',
+  'subresourcesCovered',
+]);
+
+function normalizeEgressPolicy(value) {
+  if (!value || typeof value !== 'object') throw new Error('browser broker returned no egress enforcement policy');
+  const layer = String(value.layer || value.enforcedAt || '');
+  if (!['network-namespace', 'egress-proxy', 'network-firewall'].includes(layer)) {
+    throw new Error('browser broker egress policy is not enforced below the browser UI');
+  }
+  const policyHash = requiredString(value.policyHash ?? value.policy_hash, 'egress policy hash', 512);
+  for (const control of REQUIRED_EGRESS_CONTROLS) {
+    if (value[control] !== true) throw new Error(`browser broker egress control is missing: ${control}`);
+  }
+  return Object.freeze({
+    layer,
+    policyHash,
+    ...Object.fromEntries(REQUIRED_EGRESS_CONTROLS.map((control) => [control, true])),
+  });
+}
+
+
+function publicSession(session) {
+  return {
+    schema: ENIGMA_BROWSER_SESSION_SCHEMA,
+    id: session.id,
+    provider: session.provider.id,
+    state: session.state,
+    createdAt: session.createdAt,
+    expiresAt: session.expiresAt,
+    idleExpiresAt: session.idleExpiresAt,
+    display: session.display,
+    tabs: session.tabs,
+    activeTabId: session.activeTabId,
+    streamUrl: session.state === 'connected' ? session.streamUrl : null,
+    privacy: {
+      ephemeralProfile: true,
+      privateNetworkBlocked: session.egressVerified === true,
+      egressLayer: session.egressPolicy?.layer || null,
+      egressPolicyHash: session.egressPolicy?.policyHash || null,
+      clipboardBlocked: true,
+      downloadsBlocked: true,
+      burnClears: ['cookies', 'cache', 'history', 'downloads', 'temporary-profile'],
+    },
+  };
+}
+
+export function createRemoteBrowserBrokerProvider(options = {}) {
+  const id = String(options.id || 'remote-neko-broker');
+  const baseUrl = new URL(requiredString(options.baseUrl, 'browser broker baseUrl', 4_096));
+  if (baseUrl.protocol !== 'https:' && !(baseUrl.protocol === 'http:' && ['127.0.0.1', 'localhost'].includes(baseUrl.hostname))) {
+    throw new TypeError('browser broker must use HTTPS outside localhost');
+  }
+  const viewerOrigin = normalizeViewerOrigin(options.viewerOrigin);
+  const apiKey = options.apiKey ? requiredString(options.apiKey, 'browser broker apiKey', 4_096) : null;
+  const timeoutMs = boundedInteger(options.timeoutMs, 'timeoutMs', 1_000, 120_000, 30_000);
+
+  async function request(route, requestOptions = {}) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error('browser broker timed out')), timeoutMs);
+    try {
+      const response = await fetch(new URL(route.replace(/^\/+/, ''), baseUrl), {
+        method: requestOptions.method || 'GET',
+        headers: {
+          Accept: 'application/json',
+          ...(requestOptions.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+          ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+          ...(requestOptions.sessionToken ? { 'X-Enigma-Browser-Session': requestOptions.sessionToken } : {}),
+        },
+        body: requestOptions.body === undefined ? undefined : JSON.stringify(requestOptions.body),
+        signal: controller.signal,
+      });
+      const payload = response.status === 204 ? {} : await response.json().catch(() => ({}));
+      if (!response.ok) throw new Error(payload?.error?.message || `browser broker failed with HTTP ${response.status}`);
+      return payload;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  function handle(value, current = {}) {
+    const session = value?.session || value;
+    if (!session || typeof session !== 'object') throw new Error('browser broker returned no session');
+    return {
+      providerSessionId: requiredString(session.id ?? current.providerSessionId, 'provider session id', 512),
+      sessionToken: requiredString(session.sessionToken ?? session.session_token ?? current.sessionToken, 'browser session token', 4_096),
+      state: session.state || current.state || 'ready',
+      streamUrl: validateViewerUrl(session.streamUrl ?? current.streamUrl ?? null, viewerOrigin),
+      tabs: normalizeTabs(session.tabs ?? current.tabs),
+      activeTabId: session.activeTabId ?? current.activeTabId ?? null,
+      egressPolicy: session.egressPolicy ?? session.egress_policy ?? current.egressPolicy ?? null,
+      egressAttestation: session.egressAttestation ?? session.egress_attestation ?? current.egressAttestation ?? null,
+    };
+  }
+
+  return Object.freeze({
+    id,
+    viewerOrigin,
+    async create({ display }) { return handle(await request('v1/sessions', { method: 'POST', body: { display } })); },
+    async status(current) { return handle(await request(`v1/sessions/${encodeURIComponent(current.providerSessionId)}/status`, { sessionToken: current.sessionToken }), current); },
+    async connect(current) { return handle(await request(`v1/sessions/${encodeURIComponent(current.providerSessionId)}/connect`, { method: 'POST', sessionToken: current.sessionToken }), current); },
+    async navigate(current, input) {
+      return request(`v1/sessions/${encodeURIComponent(current.providerSessionId)}/navigate`, {
+        method: 'POST', sessionToken: current.sessionToken, body: { url: input.url, tabId: input.tabId || null },
+      });
+    },
+    async control(current, input) {
+      return request(`v1/sessions/${encodeURIComponent(current.providerSessionId)}/control`, {
+        method: 'POST', sessionToken: current.sessionToken, body: input,
+      });
+    },
+    async render(current) {
+      return request(`v1/sessions/${encodeURIComponent(current.providerSessionId)}/render`, { sessionToken: current.sessionToken });
+    },
+    async destroy(current) {
+      await request(`v1/sessions/${encodeURIComponent(current.providerSessionId)}`, { method: 'DELETE', sessionToken: current.sessionToken });
+      try {
+        await request(`v1/sessions/${encodeURIComponent(current.providerSessionId)}/status`, { sessionToken: current.sessionToken });
+      } catch (error) {
+        if (/not found|ended|404/i.test(error.message)) return;
+        throw error;
+      }
+      throw new Error('browser broker cleanup verification failed: session still exists');
+    },
+  });
+}
+
+export function createDisposableBrowserRuntime(options = {}) {
+  const provider = options.provider;
+  if (!provider || typeof provider.create !== 'function' || typeof provider.destroy !== 'function') {
+    throw new TypeError('disposable browser requires an OS/container-isolated broker provider');
+  }
+  const ttlMs = boundedInteger(options.ttlMs, 'ttlMs', 60_000, 24 * 60 * 60_000, 60 * 60_000);
+  const idleTtlMs = boundedInteger(options.idleTtlMs, 'idleTtlMs', 60_000, ttlMs, 10 * 60_000);
+  const maxSessions = boundedInteger(options.maxSessions, 'maxSessions', 1, 20, 3);
+  const viewerOrigin = normalizeViewerOrigin(options.viewerOrigin || provider.viewerOrigin);
+  if (typeof options.verifyEgressAttestation !== 'function') {
+    throw new TypeError('disposable browser requires verifyEgressAttestation(); interactive browsing is disabled without broker-side egress proof');
+  }
+  const sessions = new Map();
+
+  async function verifyProviderState(session, state) {
+    const egressPolicy = normalizeEgressPolicy(state?.egressPolicy);
+    const viewerUrl = validateViewerUrl(state?.streamUrl || null, viewerOrigin);
+    if (session?.egressPolicy && session.egressPolicy.policyHash !== egressPolicy.policyHash) {
+      throw new Error('browser broker changed its egress policy during the session');
+    }
+    const verified = await options.verifyEgressAttestation(state.egressAttestation, {
+      provider: provider.id,
+      providerSessionId: state.providerSessionId,
+      policy: egressPolicy,
+      viewerOrigin,
+      viewerUrl,
+    });
+    if (verified !== true) throw new Error('browser broker egress attestation verification failed');
+    return egressPolicy;
+  }
+
+  async function applyProviderState(session, state) {
+    if (!state) return;
+    session.egressPolicy = await verifyProviderState(session, state);
+    session.egressVerified = true;
+    session.handle = { ...session.handle, ...state };
+    session.state = state.state || session.state;
+    session.tabs = normalizeTabs(state.tabs ?? session.tabs);
+    session.activeTabId = state.activeTabId ?? session.activeTabId;
+    session.streamUrl = state.streamUrl ?? session.streamUrl;
+    session.idleExpiresAt = Math.min(session.expiresAt, Date.now() + idleTtlMs);
+  }
+
+  async function burn(id) {
+    const session = sessions.get(requiredString(id, 'session id', 512));
+    if (!session) throw new Error('browser session not found');
+    if (session.state === 'burned') return publicSession(session);
+    session.state = 'burning';
+    try {
+      await provider.destroy(session.handle);
+    } catch (error) {
+      session.state = 'cleanup_failed';
+      const cleanupError = new Error(`browser cleanup failed; retry burn: ${error.message}`);
+      cleanupError.code = 'cleanup_failed';
+      throw cleanupError;
+    }
+    session.state = 'burned';
+    session.streamUrl = null;
+    session.tabs = [];
+    session.handle = null;
+    return publicSession(session);
+  }
+
+  async function get(id, { allowTerminal = false } = {}) {
+    const session = sessions.get(requiredString(id, 'session id', 512));
+    if (!session) throw new Error('browser session not found');
+    if (session.state === 'cleanup_failed' && !allowTerminal) throw new Error('browser session cleanup failed; retry burn');
+    if (Date.now() >= session.expiresAt || Date.now() >= session.idleExpiresAt) await burn(session.id);
+    if (!allowTerminal && TERMINAL.has(session.state)) throw new Error(`browser session is ${session.state}`);
+    return session;
+  }
+
+  async function refresh(session) {
+    if (!TERMINAL.has(session.state) && session.state !== 'cleanup_failed' && provider.status) {
+      await applyProviderState(session, await provider.status(session.handle));
+    }
+    return publicSession(session);
+  }
+
+  return Object.freeze({
+    async create(input = {}) {
+      const active = [...sessions.values()].filter((session) => !TERMINAL.has(session.state)).length;
+      if (active >= maxSessions) throw new Error('browser session capacity reached');
+      const display = normalizeDisplay(input.display || {});
+      const now = Date.now();
+      const state = await provider.create({ display });
+      const egressPolicy = await verifyProviderState(null, state);
+      const session = {
+        id: randomUUID(), provider, handle: state, state: state.state || 'ready', createdAt: now,
+        expiresAt: now + ttlMs, idleExpiresAt: Math.min(now + ttlMs, now + idleTtlMs), display,
+        tabs: normalizeTabs(state.tabs), activeTabId: state.activeTabId || null, streamUrl: state.streamUrl || null,
+        egressPolicy, egressVerified: true,
+      };
+      sessions.set(session.id, session);
+      return publicSession(session);
+    },
+    async status(id) { return refresh(await get(id)); },
+    async connect(id) {
+      const session = await get(id);
+      if (!provider.connect) throw new Error('browser provider does not support interactive streaming');
+      await applyProviderState(session, await provider.connect(session.handle));
+      if (!session.streamUrl) throw new Error('browser provider returned no stream URL');
+      session.state = 'connected';
+      return publicSession(session);
+    },
+    async navigate(id, input = {}) {
+      const session = await get(id);
+      const url = await assertPublicNavigationUrl(input.url, options.lookup || dns.lookup);
+      await provider.navigate(session.handle, { url, tabId: input.tabId || session.activeTabId });
+      session.idleExpiresAt = Math.min(session.expiresAt, Date.now() + idleTtlMs);
+      return refresh(session);
+    },
+    async control(id, input = {}) {
+      const session = await get(id);
+      const action = requiredString(input.action, 'action', 64);
+      if (!CONTROL_ACTIONS.has(action)) throw new TypeError(`unsupported browser control action: ${action}`);
+      const result = await provider.control(session.handle, { ...input, action, tabId: input.tabId || session.activeTabId });
+      session.idleExpiresAt = Math.min(session.expiresAt, Date.now() + idleTtlMs);
+      return { ok: true, result, session: await refresh(session) };
+    },
+    async render(id) {
+      const session = await get(id);
+      const render = await provider.render(session.handle);
+      if (!render || typeof render !== 'object') throw new Error('browser provider returned no render result');
+      return render;
+    },
+    burn,
+    async close() {
+      await Promise.all([...sessions.values()].filter((session) => session.state !== 'burned').map((session) => burn(session.id)));
+    },
+  });
+}
+
+export function createEgressAttestationVerifier(options = {}) {
+  const publicKey = createPublicKey(requiredString(options.publicKey, 'egress attestation public key', 16_384));
+  const clockSkewMs = boundedInteger(options.clockSkewMs, 'clockSkewMs', 0, 300_000, 30_000);
+  return async function verifyEgressAttestation(attestation, context) {
+    try {
+      if (!attestation || typeof attestation !== 'object') return false;
+      const payloadBytes = Buffer.from(requiredString(attestation.payload, 'egress attestation payload', 32_768), 'base64url');
+      const signature = Buffer.from(requiredString(attestation.signature, 'egress attestation signature', 4_096), 'base64url');
+      if (!verifySignature(null, payloadBytes, publicKey, signature)) return false;
+      const payload = JSON.parse(payloadBytes.toString('utf8'));
+      if (payload.schema !== 'enigma.browser_egress_attestation.v1') return false;
+      if (payload.provider !== context.provider || payload.providerSessionId !== context.providerSessionId) return false;
+      if (payload.policyHash !== context.policy.policyHash) return false;
+      if (payload.viewerOrigin !== context.viewerOrigin) return false;
+      if ((payload.viewerUrl || null) !== (context.viewerUrl || null)) return false;
+      const expiresAt = Date.parse(payload.expiresAt);
+      if (!Number.isFinite(expiresAt) || expiresAt + clockSkewMs < Date.now()) return false;
+      return true;
+    } catch {
+      return false;
+    }
+  };
+}

package/packages/inference-runtime/src/chat.js

@@ -0,0 +1,265 @@
+import { randomUUID } from 'node:crypto';
+
+export const ENIGMA_CHAT_RESPONSE_SCHEMA = 'enigma.chat_response.v1';
+
+function normalizeRequest(input = {}) {
+  if (!Array.isArray(input.messages) || !input.messages.length) throw new TypeError('messages must be a non-empty array');
+  const messages = input.messages.map((message, index) => {
+    if (!message || typeof message !== 'object') throw new TypeError(`messages[${index}] must be an object`);
+    const role = String(message.role || '');
+    if (!['system', 'user', 'assistant', 'tool'].includes(role)) throw new TypeError(`messages[${index}].role is invalid`);
+    if (typeof message.content !== 'string' && !Array.isArray(message.content)) throw new TypeError(`messages[${index}].content is invalid`);
+    return { ...message, role };
+  });
+  const privacyMode = String(input.privacyMode ?? input.privacy_mode ?? 'smart').toLowerCase();
+  if (!['off', 'smart', 'full'].includes(privacyMode)) throw new TypeError('privacy mode must be off, smart, or full');
+  const reasoningEffort = input.reasoningEffort ?? input.reasoning_effort;
+  if (reasoningEffort !== undefined && !['none', 'low', 'medium', 'high'].includes(reasoningEffort)) {
+    throw new TypeError('reasoning effort must be none, low, medium, or high');
+  }
+  return {
+    messages,
+    model: String(input.model || 'enigma-auto'),
+    temperature: Number.isFinite(input.temperature) ? Math.max(0, Math.min(2, input.temperature)) : 0.7,
+    maxTokens: Number.isInteger(input.maxTokens ?? input.max_tokens) ? Math.max(1, Math.min(131_072, input.maxTokens ?? input.max_tokens)) : 2_048,
+    stream: input.stream === true,
+    privacyMode,
+    privacyProof: input.privacyProof !== false && input.privacy_proof !== false,
+    reasoningEffort,
+    webSearch: input.webSearch === true || input.web_search === true,
+    tools: Array.isArray(input.tools) ? input.tools : undefined,
+    requirePrivateRoute: input.requirePrivateRoute === true || input.require_private_route === true,
+    council: normalizeCouncil(input.council),
+    signal: input.signal,
+  };
+}
+
+function normalizeCouncil(value) {
+  if (!value) return null;
+  if (typeof value !== 'object') throw new TypeError('council must be an object');
+  const models = [...new Set((value.models || []).map(String).filter(Boolean))].slice(0, 8);
+  if (models.length < 2) throw new TypeError('council requires at least two distinct models');
+  return { models, synthesizer: String(value.synthesizer || 'enigma-auto') };
+}
+
+function sumUsage(results) {
+  return results.reduce((sum, result) => {
+    const usage = result?.usage || {};
+    sum.prompt_tokens += Number(usage.prompt_tokens || usage.input_tokens || 0);
+    sum.completion_tokens += Number(usage.completion_tokens || usage.output_tokens || 0);
+    sum.total_tokens += Number(usage.total_tokens || 0);
+    return sum;
+  }, { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 });
+}
+
+function sseEvent(type, payload) {
+  return { type, at: Date.now(), ...payload };
+}
+
+export function createChatBackend(options = {}) {
+  const router = options.router;
+function routeDisclosure(route, fallbackModel) {
+  return {
+    model: route?.model || fallbackModel || 'unknown',
+    provider: route?.provider || 'unknown',
+    trust: route?.trust || 'unknown',
+    retentionPolicy: route?.retentionPolicy || 'unknown',
+    retentionEvidence: route?.retentionEvidence || null,
+  };
+}
+
+function aggregateRetention(routes) {
+  const normalized = routes.map((route) => routeDisclosure(route));
+  const policies = new Set(normalized.map((route) => route.retentionPolicy));
+  const policy = policies.has('unknown') ? 'unknown' : policies.size === 1 ? [...policies][0] : 'mixed';
+  return { policy, routes: normalized };
+}
+
+  const privacy = options.privacy;
+  if (!router || typeof router.complete !== 'function' || typeof router.listModels !== 'function') {
+    throw new TypeError('chat backend requires a model router');
+  }
+  if (!privacy || typeof privacy.minimize !== 'function') throw new TypeError('chat backend requires a Smart Privacy engine');
+
+  async function runSingle(request, minimized, privateState, callbacks) {
+    let sawStreamDelta = false;
+    const result = await router.complete({
+      model: request.model,
+      messages: minimized.messages,
+      temperature: request.temperature,
+      maxTokens: request.maxTokens,
+      stream: request.stream,
+      reasoningEffort: request.reasoningEffort,
+      webSearch: request.webSearch,
+      tools: request.tools,
+      requirePrivateRoute: request.requirePrivateRoute,
+      safeForExternal: minimized.safeForExternal,
+      signal: request.signal,
+    }, {
+      onEvent(event) {
+        if (event.type === 'delta') {
+          sawStreamDelta = true;
+          const delta = privateState.restoreChunk(event.delta);
+          if (delta) callbacks.onEvent?.(sseEvent('delta', { delta }));
+          return;
+        }
+        if (event.type === 'thinking') {
+          const delta = privateState.restore(event.delta);
+          callbacks.onEvent?.(sseEvent('thinking', { delta }));
+          return;
+        }
+        callbacks.onEvent?.(sseEvent(event.type, event));
+      },
+    });
+    if (sawStreamDelta) {
+      const tail = privateState.restoreChunk('', { final: true });
+      if (tail) callbacks.onEvent?.(sseEvent('delta', { delta: tail }));
+    }
+    return { ...result, answer: privateState.restore(result.answer), thinking: result.thinking ? privateState.restore(result.thinking) : null };
+  }
+
+  async function runCouncil(request, minimized, privateState, callbacks) {
+    callbacks.onEvent?.(sseEvent('council', { status: 'started', panelSize: request.council.models.length }));
+    const candidates = await Promise.all(request.council.models.map(async (model, index) => {
+      callbacks.onEvent?.(sseEvent('council', { status: 'candidate_started', index, model }));
+      let attemptedRoute = routeDisclosure(null, model);
+      try {
+        const result = await router.complete({
+          model,
+          messages: minimized.messages,
+          temperature: request.temperature,
+          maxTokens: request.maxTokens,
+          stream: false,
+          reasoningEffort: request.reasoningEffort,
+          webSearch: request.webSearch,
+          requirePrivateRoute: request.requirePrivateRoute,
+          safeForExternal: minimized.safeForExternal,
+          signal: request.signal,
+        }, {
+          onEvent(event) {
+            if (event.type === 'route') attemptedRoute = routeDisclosure(event, model);
+          },
+        });
+        attemptedRoute = routeDisclosure(result.route, model);
+        callbacks.onEvent?.(sseEvent('council', { status: 'candidate_done', index, model }));
+        return { model, result, attemptedRoute };
+      } catch (error) {
+        callbacks.onEvent?.(sseEvent('council', { status: 'candidate_failed', index, model, message: error.message }));
+        return { model, error, attemptedRoute };
+      }
+    }));
+    const successful = candidates.filter((candidate) => candidate.result);
+    if (!successful.length) {
+      const error = new Error('every council candidate failed');
+      error.code = 'council_failed';
+      error.retentionDisclosure = aggregateRetention(candidates.map((candidate) => candidate.attemptedRoute));
+      throw error;
+    }
+    const candidateText = successful.map((candidate, index) => `Candidate ${index + 1} (${candidate.model}):\n${candidate.result.answer}`).join('\n\n');
+    const synthesisMessages = [
+      ...minimized.messages,
+      {
+        role: 'system',
+        content: 'Synthesize the strongest complete answer from the candidate responses below. Correct errors; do not mention the panel or candidates.',
+      },
+      { role: 'user', content: candidateText },
+    ];
+    callbacks.onEvent?.(sseEvent('council', { status: 'synthesizing', successful: successful.length, failed: candidates.length - successful.length }));
+    let synthesisRoute = routeDisclosure(null, request.council.synthesizer);
+    const synthesis = await router.complete({
+      model: request.council.synthesizer,
+      messages: synthesisMessages,
+      temperature: Math.min(request.temperature, 0.5),
+      maxTokens: request.maxTokens,
+      stream: false,
+      reasoningEffort: request.reasoningEffort || 'high',
+      requirePrivateRoute: request.requirePrivateRoute,
+      safeForExternal: minimized.safeForExternal,
+      signal: request.signal,
+    }, {
+      onEvent(event) {
+        if (event.type === 'route') synthesisRoute = routeDisclosure(event, request.council.synthesizer);
+      },
+    });
+    synthesisRoute = routeDisclosure(synthesis.route, request.council.synthesizer);
+    callbacks.onEvent?.(sseEvent('council', { status: 'done', successful: successful.length, failed: candidates.length - successful.length }));
+    return {
+      ...synthesis,
+      answer: privateState.restore(synthesis.answer),
+      thinking: synthesis.thinking ? privateState.restore(synthesis.thinking) : null,
+      usage: sumUsage([...successful.map((candidate) => candidate.result), synthesis]),
+      retentionDisclosure: aggregateRetention([
+        ...candidates.map((candidate) => candidate.attemptedRoute),
+        synthesisRoute,
+      ]),
+      council: {
+        models: request.council.models,
+        synthesizer: synthesis.route.model,
+        successful: successful.length,
+        failed: candidates.length - successful.length,
+        receipts: [...successful.map((candidate) => candidate.result.receipt), synthesis.receipt],
+        retention_routes: [
+          ...candidates.map((candidate) => ({ ...candidate.attemptedRoute, status: candidate.result ? 'succeeded' : 'failed' })),
+          { ...synthesisRoute, status: 'succeeded', role: 'synthesizer' },
+        ],
+      },
+    };
+  }
+
+  return Object.freeze({
+    listModels: () => router.listModels(),
+    async complete(input = {}, callbacks = {}) {
+      const request = normalizeRequest(input);
+      callbacks.onEvent?.(sseEvent('privacy', { status: 'minimizing', mode: request.privacyMode }));
+      const minimized = await privacy.minimize(request.messages, { mode: request.privacyMode });
+      const privateState = minimized.privateState;
+      callbacks.onEvent?.(sseEvent('privacy', {
+        status: 'ready',
+        mode: request.privacyMode,
+        summary: minimized.receipt.summary,
+        safeForExternal: minimized.safeForExternal,
+      }));
+      const startedAt = Date.now();
+      try {
+        const result = request.council
+          ? await runCouncil(request, minimized, privateState, callbacks)
+          : await runSingle(request, minimized, privateState, callbacks);
+        const response = {
+          id: `chatcmpl_${randomUUID()}`,
+          object: 'chat.completion',
+          created: Math.floor(Date.now() / 1_000),
+          model: result.route.model,
+          choices: [{
+            index: 0,
+            message: { role: 'assistant', content: result.answer, ...(result.thinking ? { reasoning_content: result.thinking } : {}) },
+            finish_reason: result.finishReason || 'stop',
+          }],
+          usage: result.usage || null,
+          enigma_parameters: {
+            schema: ENIGMA_CHAT_RESPONSE_SCHEMA,
+            route: result.route,
+            route_receipt: result.receipt,
+            privacy: request.privacyProof ? minimized.receipt : undefined,
+            council: result.council || undefined,
+            retention: result.retentionDisclosure?.policy || result.route.retentionPolicy || 'unknown',
+            retention_evidence: result.retentionDisclosure?.routes || result.route.retentionEvidence || null,
+            elapsed_ms: Date.now() - startedAt,
+          },
+        };
+        await options.onUsage?.({
+          modality: 'text',
+          provider: result.route.provider,
+          model: result.route.model,
+          inputTokens: Number(result.usage?.prompt_tokens || 0),
+          outputTokens: Number(result.usage?.completion_tokens || 0),
+          totalTokens: Number(result.usage?.total_tokens || 0),
+          routeReceiptId: result.receipt.receiptId,
+        });
+        callbacks.onEvent?.(sseEvent('done', { response }));
+        return response;
+      } finally {
+        privateState.dispose();
+      }
+    },
+  });
+}