@yeaft/webchat-agent 1.0.415 → 1.0.417

package/local-runtime/agent/container-manager.js

@@ -0,0 +1,189 @@
+import { spawn } from 'node:child_process';
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+export const DEFAULT_AGENT_IMAGE = 'ghcr.io/yeaft/yeaft-web-code-agent-agent:dev';
+const NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}$/;
+
+export class ContainerAgentError extends Error {
+  constructor(code, message = code) {
+    super(message);
+    this.name = 'ContainerAgentError';
+    this.code = code;
+  }
+}
+
+export function normalizeContainerAgentName(name) {
+  const value = String(name || '').trim();
+  if (!NAME_PATTERN.test(value)) throw new ContainerAgentError('CONTAINER_AGENT_INVALID_NAME');
+  return value;
+}
+
+export function containerNameForAgent(name) {
+  return `yeaft-agent-${normalizeContainerAgentName(name)}`;
+}
+
+export async function runDocker(args, { spawnImpl = spawn, allowFailure = false, stdout = 'pipe' } = {}) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawnImpl('docker', args, {
+      stdio: ['ignore', stdout, 'pipe'],
+      windowsHide: true,
+    });
+    const output = [];
+    const errors = [];
+    child.stdout?.on('data', chunk => output.push(chunk));
+    child.stderr?.on('data', chunk => errors.push(chunk));
+    child.once('error', error => reject(new ContainerAgentError('CONTAINER_AGENT_DOCKER_UNAVAILABLE', error.message)));
+    child.once('close', code => {
+      const result = {
+        code: code ?? 1,
+        stdout: Buffer.concat(output).toString('utf8').trim(),
+        stderr: Buffer.concat(errors).toString('utf8').trim(),
+      };
+      if (result.code === 0 || allowFailure) resolvePromise(result);
+      else reject(new ContainerAgentError('CONTAINER_AGENT_DOCKER_FAILED', result.stderr || `docker ${args[0]} failed`));
+    });
+  });
+}
+
+export async function writeAgentSecretFile(path, secret) {
+  const value = String(secret || '').trim();
+  if (!value) throw new ContainerAgentError('CONTAINER_AGENT_SECRET_REQUIRED');
+  const absolute = resolve(path);
+  await mkdir(dirname(absolute), { recursive: true, mode: 0o700 });
+  await writeFile(absolute, `${value}\n`, { mode: 0o600 });
+  await chmod(absolute, 0o600);
+  return absolute;
+}
+
+export function buildCreateArgs({
+  name,
+  serverUrl,
+  secretFile,
+  image = DEFAULT_AGENT_IMAGE,
+  dataVolume,
+  workspaceVolume,
+  restart = 'unless-stopped',
+}) {
+  const agentName = normalizeContainerAgentName(name);
+  if (!String(serverUrl || '').match(/^wss?:\/\//)) {
+    throw new ContainerAgentError('CONTAINER_AGENT_INVALID_SERVER_URL');
+  }
+  if (!secretFile) throw new ContainerAgentError('CONTAINER_AGENT_SECRET_REQUIRED');
+  const containerName = containerNameForAgent(agentName);
+  const safeImage = String(image || '').trim();
+  if (!safeImage || safeImage.startsWith('-')) throw new ContainerAgentError('CONTAINER_AGENT_INVALID_IMAGE');
+  return [
+    'create', '--name', containerName,
+    '--label', 'io.yeaft.container-agent=true',
+    '--label', `io.yeaft.agent-name=${agentName}`,
+    '--restart', restart,
+    '--init',
+    '--mount', `type=volume,src=${dataVolume || `${containerName}-data`},dst=/home/yeaft/.yeaft`,
+    '--mount', `type=volume,src=${workspaceVolume || `${containerName}-workspace`},dst=/workspace`,
+    '--mount', `type=bind,src=${resolve(secretFile)},dst=/run/yeaft-host-secret,readonly`,
+    '--env', `SERVER_URL=${serverUrl}`,
+    '--env', `AGENT_NAME=${agentName}`,
+    '--env', 'AGENT_SECRET_FILE=/run/yeaft-host-secret',
+    '--env', 'YEAFT_DIR=/home/yeaft/.yeaft',
+    '--env', 'WORK_DIR=/workspace',
+    safeImage,
+  ];
+}
+
+/**
+ * Verify that the Docker client can reach a daemon before the Server advertises
+ * container Agent lifecycle support.
+ *
+ * @param {object} options runDocker overrides used by tests and alternate runtimes
+ * @returns {Promise<{serverVersion: string|null}>}
+ */
+export async function checkContainerAgentRuntime(options = {}) {
+  const result = await runDocker(['version', '--format', '{{.Server.Version}}'], options);
+  return { serverVersion: result.stdout || null };
+}
+
+export async function inspectContainerAgent(name, options = {}) {
+  const result = await runDocker([
+    'inspect', '--format', '{{json .State}}', containerNameForAgent(name),
+  ], { ...options, allowFailure: true });
+  if (result.code !== 0) {
+    if (/no such (object|container)/i.test(result.stderr)) {
+      return { exists: false, status: 'absent', running: false };
+    }
+    throw new ContainerAgentError('CONTAINER_AGENT_DOCKER_FAILED', result.stderr || 'docker inspect failed');
+  }
+  try {
+    const state = JSON.parse(result.stdout);
+    return {
+      exists: true,
+      status: state.Status || 'unknown',
+      running: state.Running === true,
+      startedAt: state.StartedAt || null,
+      error: state.Error || null,
+    };
+  } catch {
+    throw new ContainerAgentError('CONTAINER_AGENT_INVALID_DOCKER_RESPONSE');
+  }
+}
+
+export async function createContainerAgent(options, runtime = {}) {
+  const current = await inspectContainerAgent(options.name, runtime);
+  if (current.exists) throw new ContainerAgentError('CONTAINER_AGENT_ALREADY_EXISTS');
+  const containerName = containerNameForAgent(options.name);
+  await runDocker(buildCreateArgs(options), runtime);
+  try {
+    await runDocker(['start', containerName], runtime);
+  } catch (error) {
+    await runDocker(['rm', '-f', containerName], { ...runtime, allowFailure: true });
+    throw error;
+  }
+  return inspectContainerAgent(options.name, runtime);
+}
+
+export async function startContainerAgent(name, runtime = {}) {
+  await runDocker(['start', containerNameForAgent(name)], runtime);
+  return inspectContainerAgent(name, runtime);
+}
+
+export async function stopContainerAgent(name, runtime = {}) {
+  await runDocker(['stop', '--time', '10', containerNameForAgent(name)], runtime);
+  return inspectContainerAgent(name, runtime);
+}
+
+function isMissingDockerVolume(stderr) {
+  return /no such volume/i.test(String(stderr || ''));
+}
+
+export async function removeContainerAgent(name, { removeVolumes = true, ...runtime } = {}) {
+  const containerName = containerNameForAgent(name);
+  const current = await inspectContainerAgent(name, runtime);
+  if (current.exists) await runDocker(['rm', '-f', containerName], runtime);
+  if (removeVolumes) {
+    for (const volume of [`${containerName}-data`, `${containerName}-workspace`]) {
+      const result = await runDocker(['volume', 'rm', volume], {
+        ...runtime,
+        allowFailure: true,
+      });
+      if (result.code !== 0 && !isMissingDockerVolume(result.stderr)) {
+        throw new ContainerAgentError(
+          'CONTAINER_AGENT_DOCKER_FAILED',
+          result.stderr || `docker volume rm ${volume} failed`,
+        );
+      }
+    }
+  }
+  return { exists: false, status: 'absent', running: false };
+}
+
+export async function logsContainerAgent(name, { follow = false, ...runtime } = {}) {
+  const args = ['logs'];
+  if (follow) args.push('--follow');
+  args.push(containerNameForAgent(name));
+  return runDocker(args, { ...runtime, stdout: follow ? 'inherit' : 'pipe' });
+}
+
+export async function readSecretInput({ secret, secretFile }) {
+  if (secretFile) return (await readFile(resolve(secretFile), 'utf8')).trim();
+  return String(secret || '').trim();
+}

package/local-runtime/server/.env.example

@@ -44,6 +44,16 @@ EMAIL_CODE_EXPIRES_IN=300000
 # Agents must provide this secret to connect
 AGENT_SECRET=agent-shared-secret
 
+# Browser Runtime (disabled by default)
+# Production deployments should configure endpoint-scoped TURN credentials.
+# BROWSER_RUNTIME_ENABLED=false
+# BROWSER_STUN_URLS=stun:stun.example.com:3478
+# BROWSER_TURN_URLS=turn:turn.example.com:3478,turns:turn.example.com:443?transport=tcp
+# BROWSER_TURN_SECRET=replace-with-coturn-rest-api-secret
+# BROWSER_TURN_TTL_SECONDS=600
+# BROWSER_ICE_TRANSPORT_POLICY=all
+# BROWSER_ROUTE_TTL_MS=900000
+
 # Server-managed Sandbox (disabled by default)
 # Docker socket access is equivalent to Host root. For Docker Compose, use the
 # explicit docker-compose.sandbox.yml override documented in docs/operations/sandbox-agent.md.

package/local-runtime/server/browser-runtime-routes.js

@@ -0,0 +1,265 @@
+import { createHmac, randomUUID } from 'node:crypto';
+import { CONFIG } from './config.js';
+import { agents, webClients } from './context.js';
+
+const MAX_ROUTES = 2048;
+const MAX_PEERS = 4096;
+const MAX_CREATE_REQUESTS = 4096;
+const CREATE_REQUEST_TTL_MS = 10 * 60_000;
+
+export const browserRoutes = new Map();
+export const browserPeers = new Map();
+const browserRequests = new Map();
+
+function key(agentId, browserSessionId) {
+  return `${String(agentId || '')}\0${String(browserSessionId || '')}`;
+}
+
+function createKey(agentId, connectionId, requestId) {
+  return `${String(agentId || '')}\0${String(connectionId || '')}\0${String(requestId || '')}`;
+}
+
+function scopeUsername({ ownerUserId, agentId, browserSessionId, peerId, connectionGeneration, endpointRole, expiresAt }) {
+  const scope = Buffer.from(JSON.stringify({
+    ownerUserId,
+    agentId,
+    browserSessionId,
+    peerId,
+    connectionGeneration,
+    endpointRole,
+    credentialId: randomUUID(),
+  })).toString('base64url');
+  return `${Math.floor(expiresAt / 1000)}:${scope}`;
+}
+
+export function mintBrowserIceServers(scope, config = CONFIG.browserRuntime) {
+  const stunServers = config.stunUrls.length > 0 ? [{ urls: [...config.stunUrls] }] : [];
+  if (config.turnUrls.length === 0) return stunServers;
+  const expiresAt = Date.now() + config.credentialTtlSeconds * 1000;
+  const username = scopeUsername({ ...scope, expiresAt });
+  const credential = createHmac('sha1', config.turnSecret).update(username).digest('base64');
+  return [
+    ...stunServers,
+    { urls: [...config.turnUrls], username, credential, expiresAt },
+  ];
+}
+
+export function browserServerIdentity(client) {
+  return Object.freeze({
+    ownerUserId: client.userId,
+    clientId: client.id,
+    webConnectionId: client.connectionId,
+    webConnectionGeneration: client.connectionGeneration,
+  });
+}
+
+export function pruneBrowserRuntimeRoutes(now = Date.now()) {
+  for (const [requestKey, request] of browserRequests) {
+    if (request.expiresAt <= now || !webClients.has(request.clientId)) browserRequests.delete(requestKey);
+  }
+  for (const [peerId, peer] of browserPeers) {
+    const client = webClients.get(peer.clientId);
+    if ((peer.expiresAt != null && peer.expiresAt <= now)
+        || !client || client.connectionId !== peer.webConnectionId) {
+      browserPeers.delete(peerId);
+    }
+  }
+}
+
+export function registerBrowserCreateRequest({ agentId, client, requestId, digest }) {
+  pruneBrowserRuntimeRoutes();
+  const requestKey = createKey(agentId, client.connectionId, requestId);
+  const existing = browserRequests.get(requestKey);
+  if (existing) {
+    if (existing.digest !== digest) return { conflict: true, request: existing };
+    return { duplicate: true, request: existing };
+  }
+  if (browserRequests.size >= MAX_CREATE_REQUESTS) return { capacity: true, request: null };
+  const request = {
+    agentId,
+    requestId,
+    serverRequestId: randomUUID(),
+    clientId: client.id,
+    ownerUserId: client.userId,
+    webConnectionId: client.connectionId,
+    webConnectionGeneration: client.connectionGeneration,
+    digest,
+    state: 'pending',
+    response: null,
+    expiresAt: Date.now() + CREATE_REQUEST_TTL_MS,
+  };
+  browserRequests.set(requestKey, request);
+  return { request };
+}
+
+export function completeBrowserRequest(agentId, msg, { consume = false } = {}) {
+  for (const [requestKey, request] of browserRequests) {
+    if (request.agentId !== agentId || request.serverRequestId !== msg.requestId || request.state !== 'pending') continue;
+    request.state = msg.type.endsWith('_error') ? 'failed' : 'completed';
+    request.response = { ...msg, requestId: request.requestId };
+    request.expiresAt = Date.now() + CREATE_REQUEST_TTL_MS;
+    if (consume) browserRequests.delete(requestKey);
+    return request;
+  }
+  return null;
+}
+
+export function registerBrowserRequest({ agentId, client, requestId, kind, browserSessionId = null }) {
+  pruneBrowserRuntimeRoutes();
+  const requestKey = createKey(agentId, client.connectionId, requestId);
+  if (browserRequests.has(requestKey) || browserRequests.size >= MAX_CREATE_REQUESTS) return null;
+  const request = {
+    agentId,
+    requestId,
+    serverRequestId: randomUUID(),
+    kind,
+    browserSessionId,
+    clientId: client.id,
+    ownerUserId: client.userId,
+    webConnectionId: client.connectionId,
+    webConnectionGeneration: client.connectionGeneration,
+    digest: '',
+    state: 'pending',
+    response: null,
+    expiresAt: Date.now() + CREATE_REQUEST_TTL_MS,
+  };
+  browserRequests.set(requestKey, request);
+  return request;
+}
+
+export function installBrowserRoute({ agentId, ownerUserId, msg }) {
+  if (!msg.browserSessionId) return null;
+  const routeKey = key(agentId, msg.browserSessionId);
+  const existing = browserRoutes.get(routeKey);
+  if (existing && existing.ownerUserId !== ownerUserId) return null;
+  if (!existing && browserRoutes.size >= MAX_ROUTES) return null;
+  const route = {
+    ownerUserId,
+    agentId,
+    browserSessionId: msg.browserSessionId,
+    revision: Number(msg.revision) || 1,
+    state: msg.state || 'ready',
+    updatedAt: Date.now(),
+  };
+  browserRoutes.set(routeKey, route);
+  return route;
+}
+
+export function getBrowserRoute(agentId, browserSessionId) {
+  return browserRoutes.get(key(agentId, browserSessionId)) || null;
+}
+
+export function deleteBrowserRoute(agentId, browserSessionId) {
+  const routeKey = key(agentId, browserSessionId);
+  const deleted = browserRoutes.delete(routeKey);
+  for (const [peerId, peer] of browserPeers) {
+    if (peer.agentId === agentId && peer.browserSessionId === browserSessionId) browserPeers.delete(peerId);
+  }
+  return deleted;
+}
+
+export function reserveBrowserPeer({ agentId, browserSessionId, client, requestId, connectionGeneration, role = 'viewer' }) {
+  pruneBrowserRuntimeRoutes();
+  const route = getBrowserRoute(agentId, browserSessionId);
+  if (!route || route.ownerUserId !== client.userId || route.state !== 'ready') return { error: 'browser_session_not_found' };
+  if (!Number.isSafeInteger(connectionGeneration) || connectionGeneration <= 0) return { error: 'browser_generation_invalid' };
+  const duplicate = [...browserPeers.values()].find(peer => (
+    peer.agentId === agentId
+      && peer.browserSessionId === browserSessionId
+      && peer.clientId === client.id
+      && peer.webConnectionId === client.connectionId
+      && peer.requestId === requestId
+      && peer.connectionGeneration === connectionGeneration
+  ));
+  if (duplicate) return { peer: duplicate, duplicate: true };
+  if (browserPeers.size >= MAX_PEERS) return { error: 'browser_peer_capacity' };
+  const peerId = randomUUID();
+  const expiresAt = Date.now() + CONFIG.browserRuntime.routeTtlMs;
+  const peer = {
+    peerId,
+    requestId,
+    ownerUserId: client.userId,
+    agentId,
+    browserSessionId,
+    clientId: client.id,
+    webConnectionId: client.connectionId,
+    webConnectionGeneration: client.connectionGeneration,
+    connectionGeneration,
+    role: role === 'interactive' ? 'interactive' : 'viewer',
+    state: 'preparing',
+    pendingOffer: null,
+    pendingCandidates: [],
+    agentCandidateCount: 0,
+    webCandidateCount: 0,
+    iceTransportPolicy: CONFIG.browserRuntime.iceTransportPolicy,
+    expiresAt,
+  };
+  browserPeers.set(peerId, peer);
+  return { peer };
+}
+
+export function getBrowserPeer(peerId) {
+  pruneBrowserRuntimeRoutes();
+  return browserPeers.get(String(peerId || '')) || null;
+}
+
+export function browserPeerMatchesClient(peer, client, message = {}) {
+  return !!peer && !!client
+    && peer.ownerUserId === client.userId
+    && peer.clientId === client.id
+    && peer.webConnectionId === client.connectionId
+    && peer.webConnectionGeneration === client.connectionGeneration
+    && peer.agentId === message.agentId
+    && peer.browserSessionId === message.browserSessionId
+    && peer.connectionGeneration === Number(message.connectionGeneration);
+}
+
+export function deleteBrowserPeer(peerId) {
+  return browserPeers.delete(String(peerId || ''));
+}
+
+export function clearBrowserRuntimeForClient(client) {
+  if (!client) return [];
+  const peers = [];
+  for (const [peerId, peer] of browserPeers) {
+    if (peer.clientId === client.id && peer.webConnectionId === client.connectionId) {
+      browserPeers.delete(peerId);
+      peers.push(peer);
+    }
+  }
+  for (const [requestKey, request] of browserRequests) {
+    if (request.clientId === client.id && request.webConnectionId === client.connectionId) {
+      browserRequests.delete(requestKey);
+    }
+  }
+  return peers;
+}
+
+export function clearBrowserRuntimeForAgent(agentId) {
+  for (const [routeKey, route] of browserRoutes) {
+    if (route.agentId === agentId) browserRoutes.delete(routeKey);
+  }
+  for (const [peerId, peer] of browserPeers) {
+    if (peer.agentId === agentId) browserPeers.delete(peerId);
+  }
+  for (const [requestKey, request] of browserRequests) {
+    if (request.agentId === agentId) browserRequests.delete(requestKey);
+  }
+}
+
+export function browserClientForPeer(peer) {
+  const client = webClients.get(peer?.clientId);
+  if (!client || client.connectionId !== peer.webConnectionId
+      || client.connectionGeneration !== peer.webConnectionGeneration) return null;
+  return client;
+}
+
+export function browserAgentForPeer(peer) {
+  return agents.get(peer?.agentId) || null;
+}
+
+export function __testResetBrowserRuntimeRoutes() {
+  browserRoutes.clear();
+  browserPeers.clear();
+  browserRequests.clear();
+}

package/local-runtime/server/client-protocol.js

@@ -1,4 +1,5 @@
 export const WORKBENCH_ROUTE_PROTOCOL = 1;
+export const BROWSER_RUNTIME_PROTOCOL = 1;
 
 /**
  * Apply the explicit browser protocol hello to one Server-owned client record.
@@ -10,5 +11,8 @@ export function applyClientHello(client, message) {
   if (message.workbenchRouteProtocol === WORKBENCH_ROUTE_PROTOCOL) {
     client.workbenchRouteProtocol = WORKBENCH_ROUTE_PROTOCOL;
   }
+  if (message.browserRuntimeProtocol === BROWSER_RUNTIME_PROTOCOL) {
+    client.browserRuntimeProtocol = BROWSER_RUNTIME_PROTOCOL;
+  }
   return true;
 }

package/local-runtime/server/config.js

@@ -80,6 +80,10 @@ function loadUsers() {
 const DEFAULT_JWT_SECRET = 'default-secret-change-in-production';
 const DEFAULT_AGENT_SECRET = 'agent-shared-secret';
 
+function commaList(value) {
+  return String(value || '').split(',').map(item => item.trim()).filter(Boolean);
+}
+
 export const CONFIG = {
   // Server settings
   port: parseInt(process.env.PORT, 10) || 3456,
@@ -115,6 +119,19 @@ export const CONFIG = {
   // Agent authentication (global fallback — per-user agent_secret is preferred)
   agentSecret: process.env.AGENT_SECRET || DEFAULT_AGENT_SECRET,
 
+  // Browser Runtime stays fail-closed until the Server rollout gate is enabled.
+  // TURN credentials use the standard time-limited HMAC username scheme; Web and
+  // Agent endpoints receive separately scoped usernames from the route ledger.
+  browserRuntime: {
+    enabled: process.env.BROWSER_RUNTIME_ENABLED === 'true',
+    iceTransportPolicy: process.env.BROWSER_ICE_TRANSPORT_POLICY === 'relay' ? 'relay' : 'all',
+    stunUrls: commaList(process.env.BROWSER_STUN_URLS),
+    turnUrls: commaList(process.env.BROWSER_TURN_URLS),
+    turnSecret: process.env.BROWSER_TURN_SECRET || '',
+    credentialTtlSeconds: Math.min(3600, Math.max(60, parseInt(process.env.BROWSER_TURN_TTL_SECONDS, 10) || 600)),
+    routeTtlMs: Math.min(60 * 60_000, Math.max(60_000, parseInt(process.env.BROWSER_ROUTE_TTL_MS, 10) || 15 * 60_000)),
+  },
+
   // A Sandbox is an ordinary yeaft-agent container managed by this Server's Docker daemon.
   // The Server controls only the container lifecycle; Agent behavior stays on the existing wire.
   sandbox: {
@@ -273,6 +290,17 @@ export function validateProductionConfig() {
   if (CONFIG.sandbox.enabled && !/^wss?:\/\//.test(CONFIG.sandbox.serverUrl)) {
     errors.push('SANDBOX_SERVER_URL must be the ws:// or wss:// URL that container Agents use to connect');
   }
+  if (CONFIG.browserRuntime.enabled) {
+    const invalidIceUrl = [...CONFIG.browserRuntime.stunUrls, ...CONFIG.browserRuntime.turnUrls]
+      .find(url => !/^(?:stun|stuns|turn|turns):/i.test(url));
+    if (invalidIceUrl) errors.push(`Invalid Browser Runtime ICE URL: ${invalidIceUrl}`);
+    if (CONFIG.browserRuntime.turnUrls.length > 0 && !CONFIG.browserRuntime.turnSecret) {
+      errors.push('BROWSER_TURN_SECRET is required when BROWSER_TURN_URLS is configured');
+    }
+    if (CONFIG.browserRuntime.iceTransportPolicy === 'relay' && CONFIG.browserRuntime.turnUrls.length === 0) {
+      errors.push('BROWSER_TURN_URLS is required when BROWSER_ICE_TRANSPORT_POLICY=relay');
+    }
+  }
 
   // Check that at least one user with a password exists (in DB or config)
   // Only warn (don't block startup) — allows first-time setup via create-user.js