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

package/src/environments.mjs

@@ -0,0 +1,207 @@
+import { chmod, mkdir, open, readFile, realpath, rename, rm, stat } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const keyPattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function checkKey(key) {
+  if (typeof key !== 'string' || !keyPattern.test(key)) throw new Error('Use a valid environment variable name.');
+}
+export function stringList(value, label) {
+  if (value === undefined) return [];
+  const values = Array.isArray(value) ? value : [value];
+  if (values.some(item => typeof item !== 'string' || !item)) throw new Error(`${label} requires a string or an array of strings.`);
+  return values;
+}
+
+export async function discoverEnvironmentFiles(cwd, environment = 'default') {
+  const candidates = ['.env', '.env.local'];
+  if (environment !== 'default') candidates.push(`.env.${environment}`, `.env.${environment}.local`);
+  const files = [];
+  for (const candidate of candidates) {
+    const filename = resolve(cwd, candidate);
+    try { if ((await stat(filename)).isFile()) files.push(filename); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  return files;
+}
+
+// Values are literal. This parser never executes commands or expands variables.
+export function parseEnvFile(source) {
+  const result = Object.create(null);
+  const lines = source.replace(/^\uFEFF/, '').replaceAll('\r\n', '\n').split('\n');
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index].trim();
+    if (!line || line.startsWith('#')) continue;
+    const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (!match) throw new Error(`Invalid environment assignment on line ${index + 1}.`);
+    let value = match[2];
+    if (value.startsWith('"') || value.startsWith("'")) {
+      const quote = value[0];
+      let end = -1;
+      for (let cursor = 1; ; cursor++) {
+        if (cursor >= value.length) {
+          if (++index >= lines.length) throw new Error('An environment value has no closing quote.');
+          value += `\n${lines[index]}`;
+        }
+        if (value[cursor] === '\\' && quote === '"') { cursor++; continue; }
+        if (value[cursor] === quote) { end = cursor; break; }
+      }
+      if (!/^\s*(?:#.*)?$/.test(value.slice(end + 1))) throw new Error(`Invalid text after an environment value on line ${index + 1}.`);
+      value = value.slice(1, end);
+      if (quote === '"') value = value.replace(/\\([nrt"\\])/g, (_, character) => ({ n: '\n', r: '\r', t: '\t', '"': '"', '\\': '\\' })[character]);
+    } else value = value.startsWith('#') ? '' : value.replace(/\s+#.*$/, '').trimEnd();
+    if (value.includes('\0')) throw new Error('Environment values cannot contain null bytes.');
+    result[match[1]] = value;
+  }
+  return result;
+}
+
+export function resolveEnvironment(config, name = 'default') {
+  if (typeof name !== 'string' || !/^[a-z][a-z0-9-]{0,47}$/.test(name)) throw new Error('Use a valid environment name.');
+  const environments = config.environments ?? {};
+  if (name !== 'default' && !Object.hasOwn(environments, name)) throw new Error(`Environment ${name} is not defined in agent-env.json.`);
+  const { environments: ignored, ...base } = config;
+  const overlay = Object.hasOwn(environments, name) ? environments[name] : {};
+  if (!overlay || typeof overlay !== 'object' || Array.isArray(overlay)) throw new Error('Environment definitions must be objects.');
+  const result = { ...base, ...overlay, env: { ...base.env, ...overlay.env } };
+  if (base.compose || overlay.compose) result.compose = { ...base.compose, ...overlay.compose };
+  if (base.services || overlay.services) {
+    result.services = { ...base.services };
+    for (const [service, value] of Object.entries(overlay.services ?? {})) {
+      result.services[service] = { ...base.services?.[service], ...value, env: { ...base.services?.[service]?.env, ...value.env } };
+    }
+  }
+  return result;
+}
+
+async function storePath({ cwd = process.cwd(), environment = 'default', home } = {}) {
+  if (!/^[a-z][a-z0-9-]{0,47}$/.test(environment)) throw new Error('Use a valid environment name.');
+  const project = await realpath(cwd);
+  const digest = createHash('sha256').update(project).digest('hex');
+  const root = resolve(home ?? process.env.AGENT_ENV_HOME ?? join(homedir(), '.local/state/agent-env'));
+  return join(root, 'secrets', digest, `${environment}.json`);
+}
+export async function readEnvironmentSecrets(options = {}) {
+  try {
+    const filename = await storePath(options);
+    const file = await open(filename, 'r');
+    try {
+      await file.chmod(0o600);
+      const values = JSON.parse(await file.readFile('utf8'));
+      if (!values || typeof values !== 'object' || Array.isArray(values)) throw new Error();
+      for (const [key, value] of Object.entries(values)) {
+        checkKey(key);
+        if (typeof value !== 'string' || value.includes('\0')) throw new Error();
+      }
+      return values;
+    } finally { await file.close(); }
+  } catch (error) {
+    if (error.code === 'ENOENT') return {};
+    throw new Error('Cannot read the private environment store. Check its permissions and JSON structure.');
+  }
+}
+async function writeSecrets(options, values) {
+  const filename = await storePath(options);
+  const directory = resolve(filename, '..');
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  await chmod(directory, 0o700);
+  const temporary = `${filename}.${randomUUID()}.tmp`;
+  try {
+    const file = await open(temporary, 'wx', 0o600);
+    try { await file.writeFile(`${JSON.stringify(values)}\n`); } finally { await file.close(); }
+    await rename(temporary, filename);
+  } finally { await rm(temporary, { force: true }); }
+}
+
+// Pass a readable stdin stream or a variable name. Literal value arguments are rejected.
+export async function setEnvironmentSecret(options) {
+  const { key, stdin, fromEnv, env = process.env } = options;
+  checkKey(key);
+  if (Object.hasOwn(options, 'value')) throw new Error('Read secrets from stdin or an environment reference.');
+  if (Boolean(stdin) === Boolean(fromEnv)) throw new Error('Select exactly one secret source: stdin or an environment reference.');
+  let value;
+  if (fromEnv) {
+    checkKey(fromEnv);
+    if (!Object.hasOwn(env, fromEnv)) throw new Error('The source environment variable is not defined.');
+    value = env[fromEnv];
+  } else {
+    if (typeof stdin === 'string' || !stdin[Symbol.asyncIterator]) throw new Error('Provide a readable stdin stream.');
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of stdin) {
+      const buffer = Buffer.from(chunk);
+      size += buffer.length;
+      if (size > 1024 * 1024) throw new Error('The secret exceeds the one megabyte limit.');
+      chunks.push(buffer);
+    }
+    value = Buffer.concat(chunks).toString('utf8').replace(/\r?\n$/, '');
+  }
+  if (typeof value !== 'string' || value.includes('\0')) throw new Error('Secrets must be strings without null bytes.');
+  const values = await readEnvironmentSecrets(options);
+  await writeSecrets(options, { ...values, [key]: value });
+  return { key };
+}
+export async function listEnvironmentSecrets(options = {}) {
+  return Object.keys(await readEnvironmentSecrets(options)).sort();
+}
+export async function unsetEnvironmentSecret(options) {
+  checkKey(options.key);
+  const values = await readEnvironmentSecrets(options);
+  const existed = Object.hasOwn(values, options.key);
+  delete values[options.key];
+  await writeSecrets(options, values);
+  return existed;
+}
+
+export async function loadEnvironment({ cwd, environment = 'default', files = [], values = {}, home, env = process.env, includeStored = true, sensitiveValues = [] }) {
+  const result = Object.create(null);
+  for (const filename of stringList(files, 'env-file')) {
+    const fileValues = parseEnvFile(await readFile(resolve(cwd, filename), 'utf8'));
+    sensitiveValues.push(...credentialValues(fileValues));
+    Object.assign(result, fileValues);
+  }
+  const secrets = await readEnvironmentSecrets({ cwd, environment, home });
+  if (includeStored) { Object.assign(result, secrets); sensitiveValues.push(...Object.values(secrets)); }
+  for (const [key, reference] of Object.entries(values)) {
+    checkKey(key);
+    if (typeof reference === 'string') result[key] = reference;
+    else if (reference && Object.keys(reference).length === 1 && typeof reference.secret === 'string') {
+      if (!Object.hasOwn(secrets, reference.secret)) throw new Error(`Private variable ${reference.secret} is not set for environment ${environment}.`);
+      result[key] = secrets[reference.secret];
+      sensitiveValues.push(result[key]);
+    } else if (reference && Object.keys(reference).length === 1 && typeof reference.env === 'string') {
+      checkKey(reference.env);
+      if (!Object.hasOwn(env, reference.env)) throw new Error(`Environment reference ${reference.env} is not defined.`);
+      result[key] = env[reference.env];
+      sensitiveValues.push(result[key]);
+    } else throw new Error(`Use a string, {secret: name}, or {env: name} for variable ${key}.`);
+    if (typeof result[key] !== 'string' || result[key].includes('\0')) throw new Error('Environment values must be strings without null bytes.');
+  }
+  return result;
+}
+
+export function credentialValues(values = {}) {
+  return Object.entries(values).filter(([key, value]) =>
+    /PASSWORD|PASSWD|(?:^|_)(?:SECRET|TOKEN|PAT|CREDENTIALS?|KEY|SALT|APIKEY|AUTHORIZATION|COOKIE)(?:_|$)/i.test(key)
+    || typeof value === 'string' && (/^[a-z][a-z0-9+.-]*:\/\/[^/\s]*:[^/\s]+@/i.test(value)
+      || /^(?:gh[pousr]_|github_pat_|npm_|sk[-_]|xox[baprs]-|AKIA[A-Z0-9]{16}|glpat-|-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----)/.test(value)))
+    .map(([, value]) => value);
+}
+
+export function sensitiveValuesForSpec(spec = {}) {
+  return [...new Set([
+    ...(spec.sensitiveValues ?? []), ...credentialValues(spec.env), ...credentialValues(spec.compose?.environment),
+    ...Object.values(spec.services ?? {}).flatMap(service => credentialValues(service.env)),
+    ...Object.values(spec.compose?.model?.services ?? {}).flatMap(service => credentialValues(service.environment).map(value => typeof value === 'string' ? value.replaceAll('$$', '$') : value)),
+  ].filter(value => typeof value === 'string').flatMap(value => [value, value.trimEnd()]).filter(Boolean))];
+}
+
+export function redactEnvironment(output, values) {
+  const strings = Array.isArray(values) ? values : Object.values(values);
+  let parts = [output];
+  for (const value of [...new Set(strings)].filter(value => typeof value === 'string' && value).sort((a, b) => b.length - a.length)) {
+    parts = parts.flatMap(part => part === null ? [null] : part.split(value).flatMap((text, index) => index ? [null, text] : [text]));
+  }
+  return parts.map(part => part === null ? '[redacted]' : part).join('');
+}

package/src/goodies.mjs

@@ -0,0 +1,71 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { detectComposeFiles } from './providers/compose.mjs';
+import { loadSpec } from './config.mjs';
+import { readEnvironmentSecrets, setEnvironmentSecret, resolveEnvironment } from './environments.mjs';
+
+export async function addService(kind, options = {}) {
+  if (!['postgres', 'redis'].includes(kind)) throw new Error('Available services: postgres, redis.');
+  const cwd = options.cwd ?? process.cwd();
+  const filename = resolve(cwd, options.config ?? 'agent-env.json');
+  let config, existing = true;
+  try { config = JSON.parse(await readFile(filename, 'utf8')); }
+  catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    existing = false;
+    const files = await detectComposeFiles(cwd);
+    config = files.length ? { provider: 'compose', compose: { files } } : { provider: 'docker', services: {} };
+  }
+  if (config.provider && !['docker', 'compose'].includes(config.provider)) throw new Error('Service templates support Docker and Compose projects.');
+  const environment = options.environment ?? 'default';
+  const existingEnvironment = environment === 'default' || Object.hasOwn(config.environments ?? {}, environment);
+  if (environment !== 'default') { config.environments ??= {}; config.environments[environment] ??= {}; }
+  const resolved = resolveEnvironment(config, environment);
+  const target = environment === 'default' ? config : config.environments[environment];
+  const port = Number(options.port ?? (kind === 'postgres' ? 55432 : 56379));
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error('Use a public port between 1024 and 65535.');
+  const postgres = kind === 'postgres';
+  const service = {
+    image: postgres ? 'postgres:16-alpine' : 'redis:7-alpine',
+    port, containerPort: postgres ? 5432 : 6379, protocol: 'tcp',
+    health: postgres ? 'pg_isready -h 127.0.0.1 -U postgres' : 'redis-cli ping',
+    volumes: { data: postgres ? '/var/lib/postgresql/data' : '/data' },
+    ...(postgres ? { env: { POSTGRES_DB: 'app', POSTGRES_PASSWORD: { secret: 'POSTGRES_PASSWORD' } } } : { command: 'redis-server --dir /data --appendonly yes' }),
+  };
+  if (config.provider === 'compose' || config.compose) {
+    const current = await loadSpec({ cwd, config: existing ? options.config : undefined, env: existingEnvironment ? environment : undefined });
+    if (current.compose.model.services[kind]) throw new Error(`Service ${kind} already exists in the Compose project.`);
+    if (Object.values(current.services).some(service => service.port === port)) throw new Error(`Port ${port} already belongs to another service.`);
+    const addonName = environment === 'default' ? 'agent-env.addons.json' : `agent-env.addons.${environment}.json`;
+    const addon = resolve(cwd, addonName);
+    let model;
+    try { model = JSON.parse(await readFile(addon, 'utf8')); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; model = { services: {}, volumes: {} }; }
+    if (model.services[kind]) throw new Error(`Service ${kind} already exists in ${addonName}.`);
+    model.services[kind] = {
+      image: service.image, ports: [`${port}:${service.containerPort}`],
+      volumes: [`${kind}-data:${service.volumes.data}`],
+      healthcheck: { test: ['CMD-SHELL', service.health], interval: '2s', timeout: '2s', retries: 30 },
+      ...(postgres ? { environment: { POSTGRES_DB: 'app', POSTGRES_PASSWORD: '${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD with agent-env env set}' } }
+        : { command: ['redis-server', '--dir', '/data', '--appendonly', 'yes'] }),
+    };
+    model.volumes[`${kind}-data`] = {};
+    target.provider = 'compose';
+    target.compose ??= {};
+    target.compose.files = [...new Set([...(resolved.compose?.files ?? await detectComposeFiles(cwd)), addonName])];
+    await writeFile(addon, `${JSON.stringify(model, null, 2)}\n`);
+  } else {
+    target.services ??= {};
+    if (resolved.services?.[kind]) throw new Error(`Service ${kind} already exists.`);
+    if (Object.values(resolved.services ?? {}).some(service => service.port === port)) throw new Error(`Port ${port} already belongs to another service.`);
+    target.services[kind] = service;
+  }
+  if (postgres) {
+    const secretOptions = { cwd, environment };
+    const values = await readEnvironmentSecrets(secretOptions);
+    if (!Object.hasOwn(values, 'POSTGRES_PASSWORD')) await setEnvironmentSecret({ ...secretOptions, key: 'POSTGRES_PASSWORD', fromEnv: 'GENERATED', env: { GENERATED: randomBytes(24).toString('base64url') } });
+  }
+  await writeFile(filename, `${JSON.stringify(config, null, 2)}\n`);
+  return { message: `Added ${kind} on localhost:${port}. Run agent-env up${environment === 'default' ? '' : ` --env ${environment}`}.` };
+}

package/src/init.mjs

@@ -0,0 +1,68 @@
+import { lstat, readFile, realpath, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { detectComposeFiles } from './providers/compose.mjs';
+import { quote } from './system.mjs';
+
+async function exists(filename) {
+  try { return (await lstat(filename)).isFile(); }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+// Return public configuration only. This function never reads environment values.
+export async function createInitialConfig(options = {}) {
+  const cwd = await realpath(options.cwd ?? process.cwd());
+  const files = await detectComposeFiles(cwd);
+  if (files.length && !options.command?.length) return { provider: 'compose', compose: { files } };
+  let manifest = {};
+  try { manifest = JSON.parse(await readFile(resolve(cwd, 'package.json'), 'utf8')); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  let manager = manifest.packageManager?.split('@')[0];
+  const locks = [['bun.lock', 'bun'], ['bun.lockb', 'bun'], ['pnpm-lock.yaml', 'pnpm'], ['yarn.lock', 'yarn'], ['package-lock.json', 'npm'], ['npm-shrinkwrap.json', 'npm']];
+  let locked = false;
+  for (const [filename, candidate] of locks) {
+    if (await exists(resolve(cwd, filename))) {
+      if (manager && manager !== candidate) throw new Error('The packageManager field conflicts with a lockfile. Select one package manager before initialization.');
+      manager = candidate;
+      locked = true;
+    }
+  }
+  manager ??= 'npm';
+  if (!['npm', 'pnpm', 'yarn', 'bun'].includes(manager)) throw new Error('Use npm, pnpm, yarn, or bun, or specify an explicit initialization command.');
+  const dependencies = { ...manifest.dependencies, ...manifest.devDependencies };
+  const frameworkPort = dependencies.astro ? 4321
+    : dependencies.vite || dependencies['@sveltejs/kit'] ? 5173
+      : dependencies['@angular/core'] ? 4200
+        : dependencies['webpack-dev-server'] ? 8080 : 3000;
+  const script = manifest.scripts?.dev ? 'dev' : manifest.scripts?.start ? 'start' : undefined;
+  const port = Number(options.port ?? frameworkPort);
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error('Public ports must be integers between 1024 and 65535.');
+  let command;
+  if (Array.isArray(options.command) && options.command.length) command = options.command.map(quote).join(' ');
+  else if (typeof options.command === 'string' && options.command.trim()) command = options.command;
+  else if (script) {
+    const executable = ['pnpm', 'yarn'].includes(manager) ? `corepack ${manager}` : manager;
+    const install = manager === 'npm' ? locked ? 'npm ci' : 'npm install'
+      : `${executable} install${locked && ['pnpm', 'bun'].includes(manager) ? ' --frozen-lockfile' : ''}`;
+    const host = dependencies.vite || dependencies.astro || dependencies.nuxt || dependencies['@sveltejs/kit'] || dependencies['webpack-dev-server'] ? ' --host 0.0.0.0'
+      : dependencies.next ? ' --hostname 0.0.0.0' : dependencies['@angular/core'] ? ' --host 0.0.0.0' : '';
+    const separator = manager === 'npm' && host ? ' --' : '';
+    command = `${install} && ${executable} run ${script}${separator}${host}${host ? ` --port ${port}` : ''}`;
+  } else throw new Error('Cannot detect a development command. Add a dev or start script, or initialize with an explicit command after --.');
+  return {
+    provider: 'docker',
+    services: { web: {
+      image: options.image ?? (manager === 'bun' ? 'oven/bun:1' : 'node:22-bookworm-slim'),
+      port, command,
+      env: { HOST: '0.0.0.0', PORT: String(port) },
+      volumes: { dependencies: '/workspace/node_modules', cache: manager === 'bun' ? '/root/.bun' : manager === 'pnpm' ? '/root/.local/share/pnpm/store' : manager === 'yarn' ? '/usr/local/share/.cache/yarn' : '/root/.npm' },
+    } },
+  };
+}
+
+export async function initialize(options = {}) {
+  const cwd = await realpath(options.cwd ?? process.cwd());
+  const config = await createInitialConfig({ ...options, cwd });
+  const filename = resolve(cwd, options.config ?? 'agent-env.json');
+  await writeFile(filename, `${JSON.stringify(config, null, 2)}\n`, { flag: 'wx' });
+  return { filename, config };
+}

package/src/locks.mjs

@@ -0,0 +1,56 @@
+import { link, open, readFile, rm, stat } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { delay } from './system.mjs';
+
+const busy = () => Object.assign(new Error('The resource is busy or locked. Retry after the active operation finishes.'), { code: 'ELOCKED' });
+
+// Publish a complete owner file atomically. A crash cannot expose an empty lock.
+async function publish(path) {
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    const file = await open(temporary, 'wx', 0o600);
+    try { await file.writeFile(String(process.pid)); await file.sync(); }
+    finally { await file.close(); }
+    await link(temporary, path);
+  } finally { await rm(temporary, { force: true }); }
+}
+
+async function acquire(path, depth = 0) {
+  if (depth > 32) throw busy();
+  try { await publish(path); return; }
+  catch (error) { if (error.code !== 'EEXIST') throw error; }
+  const recovery = `${path}.recovery`;
+  // Recovery locks use the same protocol, including recovery after their owner dies.
+  await acquire(recovery, depth + 1);
+  try {
+    let contents;
+    try { contents = await readFile(path, 'utf8'); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (contents !== undefined) {
+      const pid = Number(contents);
+      if (!contents.trim()) {
+        if (Date.now() - (await stat(path)).mtimeMs < 5000) throw busy();
+      } else {
+        if (!Number.isSafeInteger(pid) || pid <= 0) throw busy();
+        try { process.kill(pid, 0); throw busy(); }
+        catch (error) { if (error.code !== 'ESRCH') throw error; }
+      }
+      await rm(path, { force: true });
+    }
+    try { await publish(path); }
+    catch (error) { if (error.code === 'EEXIST') throw busy(); throw error; }
+  } finally { await rm(recovery, { force: true }); }
+}
+
+export async function withFileLock(path, work, { waitMs = 0 } = {}) {
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    try { await acquire(path); break; }
+    catch (error) {
+      if (error.code !== 'ELOCKED' || Date.now() >= deadline) throw error;
+      await delay(50);
+    }
+  }
+  try { return await work(); }
+  finally { await rm(path, { force: true }); }
+}

package/src/maintenance.mjs

@@ -0,0 +1,74 @@
+import { redact } from './runtime.mjs';
+
+export function cloudPeers(handle, instances) {
+  const recordId = handle.spec.cloud?.recordId;
+  return recordId ? Object.values(instances).filter(peer => peer.spec.cloud?.recordId === recordId) : [];
+}
+
+export function cloudCanSleep(handle, instances) {
+  return !!handle.spec.cloud?.recordId && !cloudPeers(handle, instances).some(peer => peer !== handle && peer.running);
+}
+
+export async function expireCloudMachine(handle, { instances, destroy, disconnect, save, forget = () => {} }) {
+  const peers = cloudPeers(handle, instances);
+  if (!peers.length) throw new Error('No owned cloud machine exists for this instance.');
+  for (const peer of peers) await disconnect(peer.spec.name);
+  await destroy(handle);
+  for (const peer of peers) {
+    delete instances[peer.spec.name];
+    forget(peer);
+  }
+  await save();
+}
+
+export async function maintainInstances({ instances, action, connected, reconnect, retries, errors, now = Date.now }) {
+  const started = now();
+  const handled = new Set();
+  const attemptLifecycle = async (key, peers, work) => {
+    if (handled.has(key)) return;
+    handled.add(key);
+    const retry = retries.get(key) ?? { next: 0, count: 0 };
+    if (started < retry.next) return;
+    try {
+      await work();
+      retries.delete(key);
+      for (const peer of peers) errors.delete(peer.spec.name);
+    } catch (error) {
+      retry.count++;
+      retry.next = now() + Math.min(60000, 1000 * 2 ** Math.min(retry.count, 6));
+      retries.set(key, retry);
+      for (const peer of peers) errors.set(peer.spec.name, redact(peer, error.message));
+    }
+  };
+  for (const handle of Object.values(instances)) {
+    const name = handle.spec.name;
+    if (instances[name] !== handle) continue;
+    const cloud = handle.spec.cloud;
+    if (cloud?.expiresAt && Date.parse(cloud.expiresAt) <= started) {
+      await attemptLifecycle(`expiry:${cloud.recordId}`, cloudPeers(handle, instances), () => action({ type: 'expire', name }));
+      continue;
+    }
+    if (!handle.running) continue;
+    const lastActivity = Math.max(handle.lastActivity ?? started, ...cloudPeers(handle, instances).map(peer => peer.lastActivity ?? started));
+    if (cloud?.idleTimeoutMs && started - lastActivity >= cloud.idleTimeoutMs) {
+      const peers = cloudPeers(handle, instances);
+      await attemptLifecycle(`idle:${cloud.recordId}`, peers, async () => {
+        for (const peer of peers) if (peer.running) await action({ type: 'down', name: peer.spec.name });
+      });
+      continue;
+    }
+    if (!handle.spec.host || connected(handle)) continue;
+    const retry = retries.get(name) ?? { next: 0, count: 0 };
+    if (started < retry.next) continue;
+    try {
+      await reconnect(handle);
+      retries.delete(name);
+      errors.delete(name);
+    } catch (error) {
+      retry.count++;
+      retry.next = now() + Math.min(60000, 1000 * 2 ** Math.min(retry.count, 6));
+      retries.set(name, retry);
+      errors.set(name, redact(handle, `Reconnecting: ${error.message}`));
+    }
+  }
+}

package/src/paths.mjs

@@ -0,0 +1,5 @@
+import { homedir } from 'node:os';
+import { resolve, join } from 'node:path';
+export const home = resolve(process.env.AGENT_ENV_HOME ?? join(homedir(), '.local/state/agent-env'));
+export const socketPath = join(home, 'control.sock');
+export const statePath = join(home, 'state.json');