@desplega.ai/agent-env 0.0.0-stage → 0.3.0

package/src/providers/docker.mjs

@@ -0,0 +1,207 @@
+import http from 'node:http';
+import { spawn } from 'node:child_process';
+import { run, quote, freePort, reachable, delay } from '../system.mjs';
+import { home } from '../paths.mjs';
+import { hash } from '../config.mjs';
+import { join } from 'node:path';
+import { mkdtempSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { sourceExclusions } from '../source-paths.mjs';
+
+// A provider owns compute and storage. The daemon owns names and local routing.
+export class DockerProvider {
+  sessions = new Map();
+  sshArgs(spec, multiplex = true) {
+    const filename = `ssh-${hash(`${spec.host}:${spec.sshConfig ?? ''}`)}`;
+    let control = join(home, filename);
+    if (multiplex) {
+      // Reserve space for OpenSSH's temporary suffix within the macOS socket path limit.
+      if (Buffer.byteLength(control) > 80) {
+        this.controlDirectory ??= mkdtempSync('/tmp/agent-env-ssh-');
+        control = join(this.controlDirectory, filename);
+      }
+      this.sessions.set(control, spec);
+    }
+    const connection = multiplex
+      ? ['-o', 'ControlMaster=auto', '-S', control, '-o', 'ControlPersist=60']
+      : ['-o', 'ControlMaster=no', '-S', 'none', '-o', 'ControlPersist=no'];
+    return [...connection, ...(spec.sshConfig ? ['-F', spec.sshConfig] : []), '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', '-o', 'ServerAliveInterval=15', '-o', 'ServerAliveCountMax=2'];
+  }
+  command(spec, args, options) {
+    return spec.host
+      ? run('ssh', [...this.sshArgs(spec), '--', spec.host, args.map(quote).join(' ')], options)
+      : run(args[0], args.slice(1), options);
+  }
+  docker(spec, args, options = {}) {
+    const inspect = args[0] === 'inspect' || ['container', 'image', 'volume', 'network'].includes(args[0]) && args[1] === 'inspect';
+    return this.command(spec, ['docker', ...args], { ...options, ...(inspect ? { errorStdout: false } : {}) });
+  }
+  prefix(spec) { return `agent-env-${spec.owner}-${spec.name}`; }
+  volume(spec, service, name) { return `${this.prefix(spec)}-${service}-${name}`; }
+  transfer(spec, source, destination, options = []) {
+    // We quote remote paths for older rsync. Prevent modern rsync from quoting them again.
+    return run('rsync', ['-az', ...options, '-e', ['ssh', ...this.sshArgs(spec)].map(quote).join(' '), source, `${spec.host}:${quote(destination)}`], {
+      env: { ...process.env, RSYNC_OLD_ARGS: '1', RSYNC_PROTECT_ARGS: '0' },
+    });
+  }
+  async sync(handle) {
+    const { spec, workspace } = handle;
+    if (!spec.host) return;
+    await this.command(spec, ['mkdir', '-p', workspace]);
+    // Rapid edits can keep the same size and timestamp. Compare file contents.
+    await this.transfer(spec, `${spec.cwd}/`, `${workspace}/`, ['--checksum', '--delete', ...sourceExclusions.map(rule => `--exclude=${rule}`)]);
+  }
+  async create(spec) {
+    await this.docker(spec, ['info', '--format', '{{.ServerVersion}}']);
+    const workspace = spec.host ? `${await this.command(spec, ['pwd'])}/.local/share/agent-env/${spec.owner}/${spec.name}` : spec.cwd;
+    if (workspace.includes(',')) throw new Error('Workspace paths cannot contain commas.');
+    const handle = { spec, workspace, services: {} };
+    const newVolumes = [];
+    await this.sync(handle);
+    const network = this.prefix(spec);
+    await this.docker(spec, ['network', 'create', '--label', `agent-env.owner=${spec.owner}`, network]);
+    try {
+      for (const [name, service] of Object.entries(spec.services)) {
+        const container = `${network}-${name}`;
+        const args = ['run', '-d', '--init', '--name', container, '--label', `agent-env.owner=${spec.owner}`, '--network', network, '--network-alias', name, '-p', `127.0.0.1::${service.containerPort}`, '--mount', `type=bind,src=${workspace},dst=/workspace`, '-w', '/workspace'];
+        for (const [volume, target] of Object.entries(service.volumes ?? {})) {
+          const volumeName = this.volume(spec, name, volume);
+          const exists = await this.docker(spec, ['volume', 'ls', '-q', '--filter', `name=^${volumeName}$`]);
+          if (!exists) newVolumes.push(volumeName);
+          await this.docker(spec, ['volume', 'create', '--label', `agent-env.owner=${spec.owner}`, volumeName]);
+          args.push('--mount', `type=volume,src=${this.volume(spec, name, volume)},dst=${target}`);
+        }
+        for (const [key, value] of Object.entries({ HOST: '0.0.0.0', PORT: String(service.containerPort), ...service.env })) args.push('-e', `${key}=${value}`);
+        args.push(service.image);
+        if (service.command) args.push('sh', '-lc', service.command);
+        // Record the name before creation so partial failures can remove it.
+        handle.services[name] = { container, ...service };
+        await this.docker(spec, args);
+      }
+      await this.wait(handle);
+      return handle;
+    } catch (error) {
+      await this.remove(handle).catch(() => {});
+      for (const volume of newVolumes) await this.docker(spec, ['volume', 'rm', volume]).catch(() => {});
+      throw error;
+    }
+  }
+  async wait(handle, deadline = Date.now() + (handle.spec.startupTimeoutSeconds ?? 60) * 1000) {
+    const seconds = handle.spec.startupTimeoutSeconds ?? 60;
+    for (const [name, service] of Object.entries(handle.services)) {
+      while (true) {
+        const info = JSON.parse(await this.docker(handle.spec, ['inspect', service.container]))[0];
+        if (!info.State.Running) {
+          const logs = await this.docker(handle.spec, ['logs', '--tail', '20', service.container], { combined: true }).catch(() => '');
+          throw new Error(`${name} exited. ${logs}`);
+        }
+        const published = info.NetworkSettings.Ports[`${service.containerPort}/tcp`]?.[0];
+        if (published) {
+          service.hostPort = Number(published.HostPort);
+          let ready = handle.spec.host
+            ? await this.command(handle.spec, ['bash', '-c', `timeout 1 bash -c 'exec 3<>/dev/tcp/127.0.0.1/${service.hostPort}'`]).then(() => true, () => false)
+            : await reachable(service.hostPort);
+          if (ready && service.protocol === 'http') {
+            ready = handle.spec.host
+              ? await this.command(handle.spec, ['bash', '-c', `timeout 2 bash -c 'exec 3<>/dev/tcp/127.0.0.1/${service.hostPort}; printf \"GET / HTTP/1.0\\r\\nHost: localhost\\r\\n\\r\\n\" >&3; IFS= read -r line <&3; [[ $line == HTTP/* ]]'`]).then(() => true, () => false)
+              : await new Promise(resolve => {
+                const req = http.get({ host: '127.0.0.1', port: service.hostPort, path: '/' }, res => { res.resume(); resolve(true); });
+                req.setTimeout(1000, () => req.destroy());
+                req.on('error', () => resolve(false));
+              });
+          }
+          if (ready && service.health) ready = await this.docker(handle.spec, ['exec', service.container, 'sh', '-lc', service.health]).then(() => true, () => false);
+          if (ready) break;
+        }
+        if (Date.now() > deadline) throw new Error(`${name} did not open its port within ${seconds} seconds. Bind the service to 0.0.0.0.`);
+        await delay(300);
+      }
+    }
+  }
+  async connect(handle) {
+    const connections = [];
+    try {
+      for (const [name, service] of Object.entries(handle.services)) {
+        if (!handle.spec.host) { connections.push({ name, backendPort: service.hostPort, close() {} }); continue; }
+        const port = await freePort();
+        const child = spawn('ssh', [...this.sshArgs(handle.spec, false), '-o', 'ExitOnForwardFailure=yes', '-N', '-L', `127.0.0.1:${port}:127.0.0.1:${service.hostPort}`, '--', handle.spec.host], { stdio: ['ignore', 'ignore', 'pipe'] });
+        let error = '';
+        child.stderr.on('data', data => { error += data; });
+        child.on('error', value => { error += value.message; });
+        connections.push({ name, backendPort: port, child, close() { child.kill('SIGTERM'); } });
+        const deadline = Date.now() + 12000;
+        while (!await reachable(port)) {
+          if (child.exitCode !== null || child.signalCode !== null || Date.now() > deadline) throw new Error(`SSH forwarding failed: ${error}`);
+          await delay(100);
+        }
+      }
+      return connections;
+    } catch (error) { for (const connection of connections) connection.close(); throw error; }
+  }
+  async start(handle) {
+    await this.sync(handle);
+    for (const service of Object.values(handle.services)) await this.docker(handle.spec, ['start', service.container]);
+    await this.wait(handle);
+  }
+  async stop(handle) {
+    await Promise.all(Object.values(handle.services).map(service => this.docker(handle.spec, ['stop', '-t', '5', service.container])));
+  }
+  async remove(handle, purge = false) {
+    for (const service of Object.values(handle.services)) {
+      const exists = await this.docker(handle.spec, ['container', 'ls', '-aq', '--filter', `name=^/${service.container}$`]);
+      if (exists) await this.docker(handle.spec, ['rm', '-f', service.container]);
+    }
+    const network = this.prefix(handle.spec);
+    const networkExists = await this.docker(handle.spec, ['network', 'ls', '-q', '--filter', `name=^${network}$`]);
+    if (networkExists) await this.docker(handle.spec, ['network', 'rm', network]);
+    if (handle.spec.host && handle.workspace.endsWith(`/.local/share/agent-env/${handle.spec.owner}/${handle.spec.name}`)) {
+      await this.command(handle.spec, ['rm', '-rf', '--', handle.workspace]);
+    }
+    if (purge) {
+      for (const [name, service] of Object.entries(handle.services)) {
+        for (const volume of Object.keys(service.volumes ?? {})) {
+          const volumeName = this.volume(handle.spec, name, volume);
+          const exists = await this.docker(handle.spec, ['volume', 'ls', '-q', '--filter', `name=^${volumeName}$`]);
+          if (exists) await this.docker(handle.spec, ['volume', 'rm', volumeName]);
+        }
+      }
+    }
+  }
+  async dispose() {
+    await Promise.all([...this.sessions.values()].map(spec =>
+      run('ssh', [...this.sshArgs(spec), '-O', 'exit', '--', spec.host]).catch(() => {})));
+    this.sessions.clear();
+    if (this.controlDirectory) {
+      await rm(this.controlDirectory, { recursive: true, force: true });
+      this.controlDirectory = undefined;
+    }
+  }
+  async status(handle) {
+    return Object.fromEntries(await Promise.all(Object.entries(handle.services).map(async ([name, service]) => {
+      const result = await this.docker(handle.spec, ['inspect', '--format', '{{.State.Status}}', service.container]).catch(() => 'unreachable');
+      return [name, result];
+    })));
+  }
+  logs(handle, name) { return this.docker(handle.spec, ['logs', '--tail', '100', handle.services[name].container], { combined: true }); }
+  exec(handle, name, command) { return this.docker(handle.spec, ['exec', handle.services[name].container, ...command], { combined: true }); }
+  async fork(handle, spec) {
+    const volumes = Object.entries(handle.services).flatMap(([name, service]) =>
+      Object.keys(service.volumes ?? {}).map(volume => ({ source: this.volume(handle.spec, name, volume), destination: this.volume(spec, name, volume) })));
+    for (const { destination } of volumes) {
+      const existing = await this.docker(spec, ['volume', 'ls', '-q', '--filter', `name=^${destination}$`]);
+      if (existing) throw new Error(`Volume ${destination} already exists. Choose a different fork name.`);
+    }
+    const created = [];
+    try {
+      for (const { source, destination } of volumes) {
+        await this.docker(spec, ['volume', 'create', '--label', `agent-env.owner=${spec.owner}`, destination]);
+        created.push(destination);
+        await this.docker(spec, ['run', '--rm', '--mount', `type=volume,src=${source},dst=/source,readonly`, '--mount', `type=volume,src=${destination},dst=/destination`, 'alpine:3', 'sh', '-c', 'cp -a /source/. /destination/']);
+      }
+      return await this.create(spec);
+    } catch (error) {
+      for (const volume of created) await this.docker(spec, ['volume', 'rm', volume]).catch(() => {});
+      throw error;
+    }
+  }
+}

package/src/providers/index.mjs

@@ -0,0 +1,13 @@
+import { DockerProvider } from './docker.mjs';
+import { SandboxProvider } from './sandbox.mjs';
+import { ComposeProvider } from './compose.mjs';
+const providers = new Map([['docker', new DockerProvider()], ['compose', new ComposeProvider()], ['sandbox', new SandboxProvider()]]);
+export function providerFor(spec) {
+  const provider = providers.get(spec.provider);
+  if (!provider) throw new Error(`Provider ${spec.provider} is not installed. Available providers: ${[...providers.keys()].join(', ')}.`);
+  return provider;
+}
+
+export async function disposeProviders() {
+  await Promise.all([...providers.values()].map(provider => provider.dispose?.()));
+}

package/src/providers/sandbox.mjs

@@ -0,0 +1,170 @@
+import { isAbsolute, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { DockerProvider } from './docker.mjs';
+
+export const SANDBOX_OPERATIONS = Object.freeze(['create', 'start', 'wait', 'connect', 'stop', 'remove', 'status', 'sync', 'logs', 'exec', 'fork']);
+export const SANDBOX_CAPABILITIES = Object.freeze([...SANDBOX_OPERATIONS, 'compose']);
+const required = ['create', 'wait', 'connect', 'status'];
+
+export function validateSandboxAdapter(adapter) {
+  if (!adapter || typeof adapter !== 'object' || !adapter.capabilities || typeof adapter.capabilities !== 'object') {
+    throw new Error('Sandbox adapter must declare explicit capabilities.');
+  }
+  for (const capability of SANDBOX_CAPABILITIES) {
+    if (typeof adapter.capabilities[capability] !== 'boolean') throw new Error(`Sandbox adapter must declare capability ${capability} as a boolean.`);
+    if (SANDBOX_OPERATIONS.includes(capability) && adapter.capabilities[capability] && typeof adapter[capability] !== 'function') {
+      throw new Error(`Sandbox adapter declares ${capability} but has no ${capability} method.`);
+    }
+  }
+  for (const capability of required) {
+    if (!adapter.capabilities[capability]) throw new Error(`Sandbox adapter requires capability ${capability}.`);
+  }
+  return adapter;
+}
+
+export function requireSandboxCapabilities(adapter, spec) {
+  const requested = spec.sandbox?.requireCapabilities ?? [];
+  if (!Array.isArray(requested) || requested.some(value => typeof value !== 'string')) throw new Error('Sandbox requireCapabilities must be an array of capability names.');
+  for (const capability of [...requested, ...(spec.compose ? ['compose'] : [])]) {
+    if (!SANDBOX_CAPABILITIES.includes(capability)) throw new Error(`Unknown sandbox capability ${capability}.`);
+    if (!adapter.capabilities[capability]) throw new Error(`Sandbox adapter does not support ${capability}.`);
+  }
+}
+
+// This bridge uses the existing container lifecycle and transport implementation.
+export function createDockerSandboxAdapter(provider = new DockerProvider()) {
+  const adapter = {
+    capabilities: Object.freeze(Object.fromEntries(SANDBOX_CAPABILITIES.map(name => [name, SANDBOX_OPERATIONS.includes(name)]))),
+    dispose: () => provider.dispose?.(),
+  };
+  for (const method of SANDBOX_OPERATIONS) adapter[method] = (...args) => provider[method](...args);
+  return adapter;
+}
+
+function adapterLocation(spec) {
+  const value = spec.sandbox?.adapter;
+  if (value === 'docker') return 'docker';
+  if (typeof value !== 'string' || !value) throw new Error('Set sandbox.adapter to docker or a local ESM module path.');
+  if (value.startsWith('file:')) {
+    const url = new URL(value);
+    if (url.search || url.hash || url.host) throw new Error('Sandbox adapter must use a local file URL without query or fragment.');
+    return pathToFileURL(fileURLToPath(url)).href;
+  }
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(value)) throw new Error('Sandbox adapter must use a local ESM module.');
+  if (!isAbsolute(value) && !isAbsolute(spec.cwd ?? '')) throw new Error('Relative sandbox adapters require an absolute spec.cwd.');
+  return pathToFileURL(resolve(spec.cwd ?? '.', value)).href;
+}
+
+function serializableHandle(handle) {
+  if (!handle || typeof handle !== 'object' || !handle.spec || !handle.services || typeof handle.services !== 'object' || Array.isArray(handle.services)) {
+    throw new Error('Sandbox adapter must return a handle with spec and services.');
+  }
+  const seen = new Set();
+  const visit = value => {
+    if (value === null || ['string', 'boolean'].includes(typeof value)) return;
+    if (typeof value === 'number' && Number.isFinite(value)) return;
+    if (typeof value !== 'object' || seen.has(value) || (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype)) {
+      throw new Error('Sandbox adapter handle must contain only JSON values.');
+    }
+    seen.add(value);
+    for (const item of Object.values(value)) visit(item);
+    seen.delete(value);
+  };
+  visit(handle);
+  for (const service of Object.values(handle.services)) {
+    if (!Number.isInteger(service?.port) || service.port < 1 || service.port > 65535 || !['http', 'tcp'].includes(service.protocol)) {
+      throw new Error('Sandbox services must declare a valid public port and protocol.');
+    }
+  }
+  return handle;
+}
+
+export class SandboxProvider {
+  constructor({ dockerProvider, load = specifier => import(specifier) } = {}) {
+    this.dockerProvider = dockerProvider;
+    this.load = load;
+    this.adapters = new Map();
+  }
+  async adapterFor(spec) {
+    const location = adapterLocation(spec);
+    const options = spec.sandbox?.options ?? {};
+    if (!options || typeof options !== 'object' || Array.isArray(options)) throw new Error('Sandbox options must be an object.');
+    const key = JSON.stringify([location, options]);
+    if (!this.adapters.has(key)) {
+      const pending = (async () => {
+        if (location === 'docker') return validateSandboxAdapter(createDockerSandboxAdapter(this.dockerProvider));
+        const module = await this.load(location);
+        if (typeof module.createAdapter !== 'function') throw new Error('Sandbox ESM module must export createAdapter(options).');
+        return validateSandboxAdapter(await module.createAdapter(options));
+      })();
+      this.adapters.set(key, pending);
+      pending.catch(() => { if (this.adapters.get(key) === pending) this.adapters.delete(key); });
+    }
+    const adapter = await this.adapters.get(key);
+    requireSandboxCapabilities(adapter, spec);
+    return { adapter, location };
+  }
+  async capabilities(spec) { return { ...(await this.adapterFor(spec)).adapter.capabilities }; }
+  async invoke(operation, spec, args) {
+    const { adapter } = await this.adapterFor(spec);
+    if (!adapter.capabilities[operation]) throw new Error(`Sandbox adapter does not support ${operation}.`);
+    return adapter[operation](...args);
+  }
+  async wrap(spec, runtime, location) {
+    serializableHandle(runtime);
+    return { spec, services: runtime.services, sandbox: { adapter: location }, runtime };
+  }
+  async create(spec) {
+    const { adapter, location } = await this.adapterFor(spec);
+    const runtime = await adapter.create(spec);
+    try { return await this.wrap(spec, runtime, location); }
+    catch (error) {
+      // An adapter must also clean partial allocation when create itself rejects.
+      if (adapter.capabilities.remove) await Promise.resolve().then(() => adapter.remove(runtime, true)).catch(() => {});
+      throw error;
+    }
+  }
+  async validateHandle(handle) {
+    serializableHandle(handle.runtime);
+    const { adapter, location } = await this.adapterFor(handle.spec);
+    if (handle.sandbox?.adapter !== location) throw new Error('Sandbox handle adapter does not match its specification.');
+    if (handle.runtime.spec.owner !== handle.spec.owner || handle.runtime.spec.name !== handle.spec.name) throw new Error('Sandbox runtime belongs to a different instance.');
+    return { adapter, location };
+  }
+  async operation(operation, handle, ...args) {
+    const { location } = await this.validateHandle(handle);
+    if (operation === 'start' && location === 'docker') handle.runtime.spec = structuredClone(handle.spec);
+    const result = await this.invoke(operation, handle.spec, [handle.runtime, ...args]);
+    serializableHandle(handle.runtime);
+    handle.services = handle.runtime.services;
+    return result;
+  }
+  start(handle) { return this.operation('start', handle); }
+  wait(handle) { return this.operation('wait', handle); }
+  connect(handle) { return this.operation('connect', handle); }
+  stop(handle) { return this.operation('stop', handle); }
+  remove(handle, purge = false) { return this.operation('remove', handle, purge); }
+  status(handle) { return this.operation('status', handle); }
+  sync(handle) { return this.operation('sync', handle); }
+  logs(handle, service) { return this.operation('logs', handle, service); }
+  exec(handle, service, argv) { return this.operation('exec', handle, service, argv); }
+  async fork(handle, destinationSpec) {
+    const source = await this.validateHandle(handle);
+    const destination = await this.adapterFor(destinationSpec);
+    if (source.adapter !== destination.adapter) throw new Error('Sandbox fork requires the same adapter and options.');
+    if (!source.adapter.capabilities.fork) throw new Error('Sandbox adapter does not support fork.');
+    const runtime = await this.invoke('fork', handle.spec, [handle.runtime, destinationSpec]);
+    try { return await this.wrap(destinationSpec, runtime, destination.location); }
+    catch (error) {
+      if (source.adapter.capabilities.remove) await Promise.resolve().then(() => source.adapter.remove(runtime, true)).catch(() => {});
+      throw error;
+    }
+  }
+  async dispose() {
+    const adapters = await Promise.allSettled(this.adapters.values());
+    this.adapters.clear();
+    const results = await Promise.allSettled(adapters.filter(item => item.status === 'fulfilled').map(item => Promise.resolve().then(() => item.value.dispose?.())));
+    const errors = results.filter(item => item.status === 'rejected').map(item => item.reason);
+    if (errors.length) throw new AggregateError(errors, 'Sandbox adapter disposal failed.');
+  }
+}

package/src/proxy.mjs

@@ -0,0 +1,149 @@
+import http from 'node:http';
+import http2 from 'node:http2';
+import net from 'node:net';
+
+function hostname(authority) {
+  try { return new URL(`http://${authority}`).hostname.toLowerCase(); }
+  catch { return ''; }
+}
+
+export function selectTarget(request, targets, selected) {
+  const host = hostname(request.headers.host ?? '');
+  const bare = ['localhost', '127.0.0.1', '[::1]'].includes(host);
+  if (!bare && !host.endsWith('.localhost')) return { status: 403, error: 'Use a localhost address.' };
+  let focused = bare;
+  let id = bare ? selected : host.slice(0, -'.localhost'.length);
+  if (bare) {
+    for (const value of [request.headers.origin, request.headers.referer]) {
+      try {
+        const source = new URL(value).hostname;
+        if (source.endsWith('.localhost')) {
+          const candidate = source.slice(0, -'.localhost'.length);
+          if (targets.has(candidate)) { id = candidate; focused = false; break; }
+        }
+      } catch { /* The header does not contain a URL. */ }
+    }
+  }
+  const target = targets.get(id);
+  return target ? { target, focused, id } : { status: 404, error: 'No running service matches this address. Run agent-env list.' };
+}
+
+function headersFor(request, port, id, secure = false) {
+  const headers = { ...request.headers, host: `localhost:${port}` };
+  for (const key of Object.keys(headers)) if (key.startsWith(':')) delete headers[key];
+  if (headers.origin) {
+    try {
+      const origin = new URL(headers.origin);
+      if (origin.hostname === hostname(request.headers.host) || origin.hostname === `${id}.localhost`) {
+        if (secure && origin.host === request.headers.host) origin.port = String(port);
+        origin.hostname = 'localhost';
+        headers.origin = origin.origin;
+      }
+    } catch { /* Preserve an origin that is not a URL. */ }
+  }
+  headers['x-forwarded-host'] = request.headers.host;
+  headers['x-forwarded-proto'] = secure ? 'https' : 'http';
+  headers['x-forwarded-for'] = request.socket.remoteAddress;
+  return headers;
+}
+
+export function createProxy(port, getRoutes, options = {}) {
+  const sockets = new Set();
+  const focusedSockets = new Set();
+  const handler = (request, response) => {
+    request.headers.host ??= request.headers[':authority'];
+    const { targets, selected } = getRoutes(request);
+    const result = selectTarget(request, targets, selected);
+    if (!result.target) {
+      response.writeHead(result.status, { 'content-type': 'text/plain' });
+      response.end(`${result.error}\n`);
+      return;
+    }
+    options.onRequest?.(result.id);
+    if (result.focused) focusedSockets.add(request.socket);
+    else focusedSockets.delete(request.socket);
+    const upstream = http.request({
+      hostname: '127.0.0.1', port: result.target.backendPort,
+      method: request.method, path: request.url, headers: headersFor(request, result.target.publicPort ?? port, result.id, !!options.tls),
+    }, (incoming) => {
+      const headers = { ...incoming.headers };
+      if (request.httpVersionMajor === 2) for (const key of ['connection', 'keep-alive', 'proxy-connection', 'transfer-encoding', 'upgrade']) delete headers[key];
+      response.writeHead(incoming.statusCode, headers);
+      incoming.pipe(response);
+      incoming.on('error', () => response.destroy());
+    });
+    upstream.on('error', () => {
+      if (!response.headersSent) response.writeHead(502, { 'content-type': 'text/plain' });
+      response.end('The service did not answer. Run agent-env logs <name>.\n');
+    });
+    request.on('aborted', () => upstream.destroy());
+    response.on('close', () => upstream.destroy());
+    request.pipe(upstream);
+  };
+  const server = options.tls ? http2.createSecureServer({ ...options.tls, allowHTTP1: true }, handler) : http.createServer(handler);
+  server.on('upgrade', (request, socket, head) => {
+    const { targets, selected } = getRoutes(request);
+    const result = selectTarget(request, targets, selected);
+    if (!result.target) {
+      socket.end(`HTTP/1.1 ${result.status} Not Found\r\nConnection: close\r\n\r\n`);
+      return;
+    }
+    options.onRequest?.(result.id);
+    socket.on('data', () => options.onRequest?.(result.id));
+    if (result.focused) focusedSockets.add(socket);
+    const upstream = net.connect(result.target.backendPort, '127.0.0.1', () => {
+      const headers = headersFor(request, result.target.publicPort ?? port, result.id, !!options.tls);
+      upstream.write(`${request.method} ${request.url} HTTP/${request.httpVersion}\r\n`);
+      for (const [key, value] of Object.entries(headers)) {
+        for (const item of Array.isArray(value) ? value : [value]) {
+          if (item !== undefined) upstream.write(`${key}: ${item}\r\n`);
+        }
+      }
+      upstream.write('\r\n');
+      if (head.length) upstream.write(head);
+      socket.pipe(upstream).pipe(socket);
+    });
+    upstream.on('error', () => socket.destroy());
+    socket.on('error', () => upstream.destroy());
+    socket.on('close', () => upstream.destroy());
+    upstream.on('close', () => socket.destroy());
+  });
+  server.on('connection', socket => {
+    sockets.add(socket);
+    socket.on('close', () => { sockets.delete(socket); focusedSockets.delete(socket); });
+  });
+  return {
+    server,
+    resetFocus() { for (const socket of focusedSockets) socket.destroy(); },
+    async close() {
+      for (const socket of sockets) socket.destroy();
+      await new Promise(resolve => server.close(resolve));
+    },
+  };
+}
+
+export function createTcpProxy(getRoutes, options = {}) {
+  const sockets = new Set();
+  const server = net.createServer(socket => {
+    const { targets, selected } = getRoutes();
+    const target = targets.get(selected);
+    if (!target) { socket.destroy(); return; }
+    options.onRequest?.(selected);
+    socket.on('data', () => options.onRequest?.(selected));
+    const upstream = net.connect(target.backendPort, '127.0.0.1');
+    sockets.add(socket);
+    socket.on('close', () => { sockets.delete(socket); upstream.destroy(); });
+    upstream.on('close', () => socket.destroy());
+    socket.on('error', () => upstream.destroy());
+    upstream.on('error', () => socket.destroy());
+    socket.pipe(upstream).pipe(socket);
+  });
+  return {
+    server,
+    resetFocus() { for (const socket of sockets) socket.destroy(); },
+    async close() {
+      for (const socket of sockets) socket.destroy();
+      await new Promise(resolve => server.close(resolve));
+    },
+  };
+}

package/src/runtime.mjs

@@ -0,0 +1,83 @@
+import { once } from 'node:events';
+import { join } from 'node:path';
+import { createProxy } from './proxy.mjs';
+import { ensureTls } from './tls.mjs';
+import { startUi } from './ui.mjs';
+import { watchSource } from './watch.mjs';
+import { hash } from './config.mjs';
+import { home } from './paths.mjs';
+import { redactEnvironment, sensitiveValuesForSpec } from './environments.mjs';
+
+export function serviceAlias(name, service, primary) {
+  if (service === primary) return name;
+  const alias = `${name}--${service}`;
+  return alias.length <= 63 ? alias : `${alias.slice(0, 54)}-${hash(alias)}`;
+}
+export function redact(handle, text) {
+  const spec = handle?.spec ?? {};
+  return redactEnvironment(String(text ?? ''), sensitiveValuesForSpec(spec));
+}
+export class RuntimeExtras {
+  constructor({ instances, connections, changed, status, logs, activity }) {
+    Object.assign(this, { instances, connections, changed, status, logs, activity });
+    this.watchers = new Map(); this.tls = null; this.ui = null;
+  }
+  routes() {
+    const targets = new Map();
+    for (const [name, opened] of this.connections()) {
+      const handle = this.instances()[name];
+      if (!handle?.running) continue;
+      const http = Object.keys(handle.services).filter(key => handle.services[key].protocol === 'http' && handle.services[key].port);
+      for (const connection of opened) {
+        if (!http.includes(connection.name)) continue;
+        const service = handle.services[connection.name];
+        const alias = serviceAlias(name, connection.name, http[0]);
+        if (targets.has(alias)) throw new Error(`HTTPS name ${alias}.localhost is ambiguous. Rename one instance.`);
+        targets.set(alias, { backendPort: connection.backendPort, publicPort: service.port, instance: name });
+      }
+    }
+    return { targets, selected: undefined };
+  }
+  async enableHttps(port = 8443) {
+    if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('Specify a valid HTTPS port.');
+    if (this.tls) return { port: this.tls.port, caPath: this.tls.caPath };
+    const credentials = await ensureTls(join(home, 'tls'), [...this.routes().targets.keys()].map(name => `${name}.localhost`));
+    const proxy = createProxy(port, () => this.routes(), { tls: credentials, onRequest: alias => this.activity(this.routes().targets.get(alias)?.instance) });
+    try { proxy.server.listen(port, '127.0.0.1'); await once(proxy.server, 'listening'); }
+    catch (error) { throw new Error(`Cannot bind HTTPS port ${port}: ${error.code}. Choose --https-port with an available port.`); }
+    this.tls = { ...proxy, port: proxy.server.address().port, caPath: credentials.caPath };
+    return { port: this.tls.port, caPath: this.tls.caPath };
+  }
+  async refreshCertificates() {
+    if (!this.tls) return;
+    const credentials = await ensureTls(join(home, 'tls'), [...this.routes().targets.keys()].map(name => `${name}.localhost`));
+    this.tls.server.setSecureContext(credentials);
+  }
+  httpsUrl(name, service, primary) {
+    return this.tls ? `https://${serviceAlias(name, service, primary)}.localhost:${this.tls.port}` : undefined;
+  }
+  async enableUi(port = 4780) {
+    if (!this.ui) this.ui = await startUi({ port, status: this.status, logs: this.logs });
+    return { url: this.ui.url };
+  }
+  watch(handle) {
+    this.unwatch(handle.spec.name);
+    if (!handle.spec.host || handle.spec.watch === false || !handle.running) return;
+    const name = handle.spec.name;
+    try {
+      this.watchers.set(name, watchSource(handle.spec.cwd, {
+        stateDirectory: home,
+        changed: () => this.changed(name),
+        error: error => { handle.syncError = error.message; },
+      }));
+      handle.syncError = null;
+    } catch (error) { handle.syncError = error.message; }
+  }
+  unwatch(name) { this.watchers.get(name)?.(); this.watchers.delete(name); }
+  async close() {
+    for (const stop of this.watchers.values()) stop();
+    this.watchers.clear();
+    await this.ui?.close();
+    await this.tls?.close();
+  }
+}