@commonlyai/cli 0.1.0

package/src/lib/environment.js

@@ -0,0 +1,326 @@
+/**
+ * Agent Environment resolver — ADR-008 Phase 1.
+ *
+ * An environment.yaml/.json file is the user-authored, driver-neutral spec for
+ * how an agent's runtime should be shaped: workspace path, sandbox mode, the
+ * Claude skills to mount, the MCP servers to expose. This module is the
+ * adapter-facing read-side: parse, validate, and realize the workspace +
+ * skill links on disk. Sandbox argv wrapping lives in `./sandbox/bwrap.js`
+ * because it is per-driver (Linux-only, bwrap-specific).
+ *
+ * Zero runtime deps: Node 20 has no built-in YAML, so we accept JSON only and
+ * surface a clear error on .yaml/.yml inputs (per task brief). When a future
+ * Node version exposes `node:yaml` natively, parseEnvironmentFile is the one
+ * place to add a `.yaml` branch — the rest of the module is parser-agnostic.
+ */
+
+import { readFile, mkdir, symlink, lstat, readlink, cp } from 'fs/promises';
+import { existsSync } from 'fs';
+import { dirname, isAbsolute, join, resolve as pathResolve, basename } from 'path';
+import { homedir } from 'os';
+
+// ── Schema — keep the allow-list narrow; ADR-008 §invariants #1+#2 ──────────
+//
+// Deliberate omission: the env file's directory (needed to resolve `seed` and
+// relative skill paths) is NOT stored on the returned spec. Leaking the user's
+// absolute filesystem path into `config.environment` sent to the backend
+// exposes `$HOME` layout for zero server-side benefit. Callers pass
+// `envFileDir` as a separate argument to resolveWorkspace / linkSkills.
+
+const ALLOWED_TOP_KEYS = new Set([
+  'version', 'workspace', 'sandbox', 'skills', 'mcp',
+]);
+const ALLOWED_SANDBOX_MODES = new Set(['none', 'bwrap', 'firejail', 'container', 'managed']);
+const ALLOWED_NETWORK_POLICIES = new Set(['unrestricted', 'restricted']);
+
+const expandHome = (p) => {
+  if (!p || typeof p !== 'string') return p;
+  if (p === '~') return homedir();
+  if (p.startsWith('~/')) return join(homedir(), p.slice(2));
+  return p;
+};
+
+// ── parseEnvironmentFile ────────────────────────────────────────────────────
+
+/**
+ * Read and parse the env file. Accepts JSON only in Phase 1 — .yaml/.yml
+ * inputs fail with a specific error pointing the user at JSON, so we never
+ * silently misread a YAML file as JSON.
+ */
+export const parseEnvironmentFile = async (absolutePath) => {
+  if (!isAbsolute(absolutePath)) {
+    throw new Error(`parseEnvironmentFile requires an absolute path, got: ${absolutePath}`);
+  }
+  if (!existsSync(absolutePath)) {
+    throw new Error(`Environment file not found: ${absolutePath}`);
+  }
+
+  const lower = absolutePath.toLowerCase();
+  if (lower.endsWith('.yaml') || lower.endsWith('.yml')) {
+    throw new Error(
+      `YAML environment files are not supported in Phase 1 — Node 20 has no `
+      + `built-in YAML parser and we keep zero runtime deps. Convert ${absolutePath} `
+      + `to JSON (same shape) and pass that instead.`,
+    );
+  }
+
+  const raw = await readFile(absolutePath, 'utf8');
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Failed to parse environment file ${absolutePath}: ${err.message}`);
+  }
+
+  const validation = validateEnvironmentSpec(parsed);
+  if (!validation.ok) {
+    throw new Error(
+      `Invalid environment spec in ${absolutePath}:\n  - ${validation.errors.join('\n  - ')}`,
+    );
+  }
+
+  // Return the bare spec — no envFileDir wrapping, no underscore-prefixed
+  // annotations. The caller is responsible for tracking envFileDir separately
+  // (compute via `dirname(envPath)`) and passing it explicitly to
+  // resolveWorkspace / linkSkills when relative paths in the spec need to
+  // resolve. This keeps the spec safe to serialize and ship to the backend
+  // (`config.environment` on AgentInstallation) without leaking $HOME layout.
+  return parsed;
+};
+
+// ── validateEnvironmentSpec ─────────────────────────────────────────────────
+
+export const validateEnvironmentSpec = (spec) => {
+  const errors = [];
+
+  if (!spec || typeof spec !== 'object' || Array.isArray(spec)) {
+    return { ok: false, errors: ['env spec must be a JSON object'] };
+  }
+
+  for (const key of Object.keys(spec)) {
+    if (!ALLOWED_TOP_KEYS.has(key)) {
+      errors.push(`unknown top-level key: "${key}" (allowed: ${[...ALLOWED_TOP_KEYS].join(', ')})`);
+    }
+  }
+
+  if (spec.version !== undefined && spec.version !== 1) {
+    errors.push(`version must be 1, got ${JSON.stringify(spec.version)}`);
+  }
+
+  if (spec.workspace !== undefined) {
+    if (typeof spec.workspace !== 'object' || spec.workspace === null) {
+      errors.push('workspace must be an object');
+    } else {
+      if (spec.workspace.path !== undefined && typeof spec.workspace.path !== 'string') {
+        errors.push('workspace.path must be a string');
+      }
+      if (spec.workspace.seed !== undefined) {
+        if (!Array.isArray(spec.workspace.seed)
+          || !spec.workspace.seed.every((s) => typeof s === 'string')) {
+          errors.push('workspace.seed must be an array of strings');
+        }
+      }
+    }
+  }
+
+  if (spec.sandbox !== undefined) {
+    if (typeof spec.sandbox !== 'object' || spec.sandbox === null) {
+      errors.push('sandbox must be an object');
+    } else {
+      const { mode, network, filesystem } = spec.sandbox;
+      if (mode !== undefined && !ALLOWED_SANDBOX_MODES.has(mode)) {
+        errors.push(`sandbox.mode must be one of: ${[...ALLOWED_SANDBOX_MODES].join(', ')}`);
+      }
+      if (network !== undefined) {
+        if (typeof network !== 'object' || network === null) {
+          errors.push('sandbox.network must be an object');
+        } else {
+          if (network.policy !== undefined && !ALLOWED_NETWORK_POLICIES.has(network.policy)) {
+            errors.push(`sandbox.network.policy must be one of: ${[...ALLOWED_NETWORK_POLICIES].join(', ')}`);
+          }
+          if (network['allow-hosts'] !== undefined
+            && (!Array.isArray(network['allow-hosts'])
+              || !network['allow-hosts'].every((h) => typeof h === 'string'))) {
+            errors.push('sandbox.network.allow-hosts must be an array of strings');
+          }
+        }
+      }
+      if (filesystem !== undefined) {
+        if (typeof filesystem !== 'object' || filesystem === null) {
+          errors.push('sandbox.filesystem must be an object');
+        } else {
+          for (const f of ['read-outside', 'write-outside']) {
+            if (filesystem[f] !== undefined
+              && (!Array.isArray(filesystem[f])
+                || !filesystem[f].every((p) => typeof p === 'string'))) {
+              errors.push(`sandbox.filesystem.${f} must be an array of strings`);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  if (spec.skills !== undefined) {
+    if (typeof spec.skills !== 'object' || spec.skills === null) {
+      errors.push('skills must be an object');
+    } else {
+      if (spec.skills.claude !== undefined
+        && (!Array.isArray(spec.skills.claude)
+          || !spec.skills.claude.every((p) => typeof p === 'string'))) {
+        errors.push('skills.claude must be an array of strings');
+      }
+      if (spec.skills.commonly !== undefined
+        && (!Array.isArray(spec.skills.commonly)
+          || !spec.skills.commonly.every((p) => typeof p === 'string'))) {
+        errors.push('skills.commonly must be an array of strings');
+      }
+    }
+  }
+
+  if (spec.mcp !== undefined) {
+    if (!Array.isArray(spec.mcp)) {
+      errors.push('mcp must be an array');
+    } else {
+      spec.mcp.forEach((server, i) => {
+        if (!server || typeof server !== 'object' || Array.isArray(server)) {
+          errors.push(`mcp[${i}] must be an object`);
+          return;
+        }
+        if (typeof server.name !== 'string' || !server.name) {
+          errors.push(`mcp[${i}].name is required and must be a non-empty string`);
+        }
+        if (server.transport !== undefined
+          && !['http', 'stdio', 'sse'].includes(server.transport)) {
+          errors.push(`mcp[${i}].transport must be one of: http, stdio, sse`);
+        }
+      });
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+};
+
+// ── resolveWorkspace ────────────────────────────────────────────────────────
+
+/**
+ * Compute the workspace path and ensure it exists. On first creation, copy
+ * any `workspace.seed` paths in. Returns `{ path, created }` so the caller
+ * can log the outcome and (in the future) gate one-time setup.
+ *
+ * `envFileDir` is the directory of the env file (used to resolve relative
+ * seed paths). Required when `workspace.seed` contains relative entries;
+ * ignored otherwise.
+ */
+export const resolveWorkspace = async (spec, agentName, envFileDir = null) => {
+  if (!agentName) throw new Error('resolveWorkspace requires agentName');
+  const declared = spec?.workspace?.path;
+  const path = expandHome(declared) || join(homedir(), '.commonly', 'workspaces', agentName);
+  const absPath = isAbsolute(path) ? path : pathResolve(path);
+
+  const created = !existsSync(absPath);
+  await mkdir(absPath, { recursive: true });
+
+  if (created && Array.isArray(spec?.workspace?.seed)) {
+    for (const entry of spec.workspace.seed) {
+      const src = isAbsolute(entry)
+        ? entry
+        : (envFileDir ? pathResolve(envFileDir, entry) : pathResolve(entry));
+      if (!existsSync(src)) {
+        throw new Error(`workspace.seed entry not found: ${src}`);
+      }
+      const dest = join(absPath, basename(src));
+      // eslint-disable-next-line no-await-in-loop
+      await cp(src, dest, { recursive: true, force: false, errorOnExist: false });
+    }
+  }
+
+  return { path: absPath, created };
+};
+
+// ── linkSkills ──────────────────────────────────────────────────────────────
+
+/**
+ * Symlink each `skills.claude[]` source path into `<workspacePath>/.claude/skills/`.
+ *
+ * Idempotent: if a symlink already points at the declared source, it is
+ * counted in `skipped` and left in place. If a DIFFERENT file or symlink
+ * occupies the slot, it is recorded in `conflicted` with a reason — never
+ * overwritten (a user-edited skill in the workspace must not be clobbered).
+ * Missing source paths are also reported in `conflicted` so the caller can
+ * surface them.
+ *
+ * `envFileDir` is the directory of the env file (used to resolve relative
+ * skill paths). Optional — when omitted, relative paths fall back to
+ * `workspacePath`. Pass it from `performAttach` for attach-time resolution
+ * matching the env file's location.
+ *
+ * Returns `{ linked, skipped, conflicted }`:
+ *   - `linked`:     string[]            — newly created symlinks (absolute source paths)
+ *   - `skipped`:    string[]            — already correctly linked (no-op)
+ *   - `conflicted`: Array<{path, reason}> where reason ∈
+ *       'different-target' | 'not-symlink' | 'missing-source'
+ */
+export const linkSkills = async (spec, workspacePath, envFileDir = null) => {
+  const sources = Array.isArray(spec?.skills?.claude) ? spec.skills.claude : [];
+  const linked = [];
+  const skipped = [];
+  const conflicted = [];
+  if (sources.length === 0) return { linked, skipped, conflicted };
+
+  const skillsDir = join(workspacePath, '.claude', 'skills');
+  await mkdir(skillsDir, { recursive: true });
+
+  for (const rawSource of sources) {
+    const source = expandHome(rawSource);
+    const absSource = isAbsolute(source)
+      ? source
+      : pathResolve(envFileDir || workspacePath, source);
+    if (!existsSync(absSource)) {
+      conflicted.push({ path: absSource, reason: 'missing-source' });
+      continue;
+    }
+    const linkPath = join(skillsDir, basename(absSource));
+
+    let existingTarget = null;
+    let slotIsNonSymlink = false;
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const stat = await lstat(linkPath);
+      if (stat.isSymbolicLink()) {
+        // eslint-disable-next-line no-await-in-loop
+        existingTarget = await readlink(linkPath);
+      } else {
+        slotIsNonSymlink = true;
+      }
+    } catch (err) {
+      // Only ENOENT means "slot is free, proceed." EACCES / EPERM / EIO are
+      // real failures that should surface — without this narrowing the
+      // subsequent symlink() call fails with a confusing follow-on error.
+      if (err.code !== 'ENOENT') throw err;
+    }
+
+    if (slotIsNonSymlink) {
+      conflicted.push({ path: absSource, reason: 'not-symlink' });
+      continue;
+    }
+
+    if (existingTarget) {
+      const resolvedExisting = isAbsolute(existingTarget)
+        ? existingTarget
+        : pathResolve(skillsDir, existingTarget);
+      if (resolvedExisting === absSource) {
+        skipped.push(absSource);
+        continue;
+      }
+      conflicted.push({ path: absSource, reason: 'different-target' });
+      continue;
+    }
+
+    // eslint-disable-next-line no-await-in-loop
+    await symlink(absSource, linkPath);
+    linked.push(absSource);
+  }
+
+  return { linked, skipped, conflicted };
+};

package/src/lib/memory-bridge.js

@@ -0,0 +1,54 @@
+/**
+ * Memory bridge — ADR-005 §Memory bridge, ADR-003 Phase 2.
+ *
+ * Two thin CAP shims the run loop calls around every spawn cycle:
+ *
+ *   readLongTerm(client)            — GET  /api/agents/runtime/memory,
+ *                                      returns sections.long_term.content or ''
+ *   syncBack(client, { summary })   — POST /api/agents/runtime/memory/sync
+ *                                      with mode:'patch', sourceRuntime:'local-cli'.
+ *                                      No-op when summary is falsy.
+ *
+ * Identity (agentName, instanceId) is derived server-side from the runtime
+ * token (agentRuntimeAuth), so neither helper needs to pass it. Keeping it
+ * server-derived is invariant-preserving: a bug in the wrapper can't write
+ * to the wrong agent's memory.
+ *
+ * ADR-003 invariant #9: the wrapper supplies `content` + `visibility` ONLY.
+ * `byteSize`, `updatedAt`, and `schemaVersion` are server-stamped; supplying
+ * them from the client is wasted bytes and the kernel discards them.
+ */
+
+export const SOURCE_RUNTIME = 'local-cli';
+
+export const readLongTerm = async (client, { onError } = {}) => {
+  try {
+    const body = await client.get('/api/agents/runtime/memory');
+    return body?.sections?.long_term?.content || '';
+  } catch (err) {
+    // A fresh agent has no memory row yet — treat as empty rather than fail
+    // the spawn. The kernel upserts on first write. For anything OTHER than
+    // a 404 (auth revoked, backend down, network out), surface via onError
+    // so the user sees "something's wrong with memory" instead of a silently
+    // context-less agent.
+    if (err?.status && err.status !== 404) {
+      onError?.(err);
+    }
+    return '';
+  }
+};
+
+export const syncBack = async (client, { summary } = {}) => {
+  if (!summary) return { skipped: true };
+  await client.post('/api/agents/runtime/memory/sync', {
+    mode: 'patch',
+    sourceRuntime: SOURCE_RUNTIME,
+    sections: {
+      long_term: {
+        content: summary,
+        visibility: 'private',
+      },
+    },
+  });
+  return { skipped: false };
+};

package/src/lib/memory-import.js

@@ -0,0 +1,156 @@
+/**
+ * Local memory import — Phase C of the retention plan ("your agent arrives
+ * whole"). Detects the memory a local agent already has on this machine
+ * (project CLAUDE.md / MEMORY.md, Claude Code's per-project auto-memory
+ * directory), composes it into one document, and promotes it into the
+ * kernel envelope's `long_term` section via POST /memory/sync.
+ *
+ * Design constraints:
+ *   - Explicitly opt-in with preview (plan D3) — local memory files can
+ *     contain private material; callers must confirm before anything is
+ *     sent. This module only detects/composes/sends; the command layer
+ *     owns the prompt.
+ *   - APPEND, never clobber: `mode: 'patch'` replaces a section wholesale
+ *     (mergePatchSections is section-level), so we read the existing
+ *     long_term and append the import after it.
+ *   - Server stamps byteSize/updatedAt/schemaVersion (ADR-003 invariant
+ *     #9); we send content + visibility only.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync, realpathSync } from 'fs';
+import { homedir } from 'os';
+import { join, basename } from 'path';
+
+export const SOURCE_RUNTIME = 'import-local';
+
+// Envelope sections are curated context, not dumps. The auto-clearer story
+// on the agent side starts caring around 400KB of session; a quarter of
+// that is a generous ceiling for a one-shot import.
+export const MAX_IMPORT_BYTES = 256 * 1024;
+
+// Claude Code keeps per-project auto-memory under
+// ~/.claude/projects/<slug>/memory where <slug> is the project path with
+// every '/' replaced by '-'.
+export const claudeProjectMemoryDir = (cwd, home) => join(
+  home,
+  '.claude',
+  'projects',
+  cwd.replaceAll('/', '-'),
+  'memory',
+);
+
+const fileCandidate = (path, label) => {
+  if (!existsSync(path)) return null;
+  const stat = statSync(path);
+  if (!stat.isFile() || stat.size === 0) return null;
+  return { path, label, bytes: stat.size };
+};
+
+/**
+ * Find importable memory sources. An explicit path wins outright (file, or
+ * directory whose *.md files are all taken); otherwise auto-detect the
+ * well-known locations. Duplicates are collapsed by realpath — this repo,
+ * for instance, symlinks AGENTS.md → CLAUDE.md.
+ */
+export const detectMemorySources = ({
+  cwd = process.cwd(),
+  home = homedir(),
+  explicitPath = null,
+} = {}) => {
+  const candidates = [];
+
+  if (explicitPath) {
+    if (!existsSync(explicitPath)) {
+      throw new Error(`No such file or directory: ${explicitPath}`);
+    }
+    if (statSync(explicitPath).isDirectory()) {
+      for (const f of readdirSync(explicitPath).filter((n) => n.endsWith('.md')).sort()) {
+        const c = fileCandidate(join(explicitPath, f), `from ${basename(explicitPath)}/`);
+        if (c) candidates.push(c);
+      }
+      if (!candidates.length) {
+        throw new Error(`No .md files found in ${explicitPath}`);
+      }
+    } else {
+      const c = fileCandidate(explicitPath, 'explicit');
+      if (!c) throw new Error(`${explicitPath} is empty or not a regular file`);
+      candidates.push(c);
+    }
+  } else {
+    const projectInstructions = fileCandidate(join(cwd, 'CLAUDE.md'), 'project instructions');
+    if (projectInstructions) candidates.push(projectInstructions);
+    const agentsMd = fileCandidate(join(cwd, 'AGENTS.md'), 'project instructions');
+    if (agentsMd) candidates.push(agentsMd);
+    const projectMemory = fileCandidate(join(cwd, 'MEMORY.md'), 'project memory');
+    if (projectMemory) candidates.push(projectMemory);
+
+    const memDir = claudeProjectMemoryDir(cwd, home);
+    if (existsSync(memDir) && statSync(memDir).isDirectory()) {
+      for (const f of readdirSync(memDir).filter((n) => n.endsWith('.md')).sort()) {
+        const c = fileCandidate(join(memDir, f), 'auto-memory');
+        if (c) candidates.push(c);
+      }
+    }
+  }
+
+  // Collapse symlink duplicates (first mention wins its label).
+  const seen = new Set();
+  return candidates.filter((c) => {
+    let real;
+    try {
+      real = realpathSync(c.path);
+    } catch {
+      real = c.path;
+    }
+    if (seen.has(real)) return false;
+    seen.add(real);
+    return true;
+  });
+};
+
+/** Compose the sources into one markdown document with per-file provenance. */
+export const composeImport = (sources) => {
+  if (!sources.length) throw new Error('Nothing to import');
+  const total = sources.reduce((n, s) => n + s.bytes, 0);
+  if (total > MAX_IMPORT_BYTES) {
+    throw new Error(
+      `Import is ${Math.round(total / 1024)}KB — over the ${MAX_IMPORT_BYTES / 1024}KB ceiling. `
+      + 'Pass an explicit --path to a smaller file, or trim the sources.',
+    );
+  }
+  const parts = sources.map((s) => {
+    const content = readFileSync(s.path, 'utf8').trim();
+    return `## Imported: ${basename(s.path)} (${s.label})\n\n${content}`;
+  });
+  return `# Imported local memory\n\n${parts.join('\n\n---\n\n')}`;
+};
+
+/**
+ * Promote the composed document into the agent's long_term section,
+ * appending after any existing content. `client` is an api.js client
+ * authenticated with the agent's runtime token.
+ */
+export const importMemory = async (client, { sources }) => {
+  const imported = composeImport(sources);
+
+  let existing = '';
+  try {
+    const body = await client.get('/api/agents/runtime/memory');
+    existing = body?.sections?.long_term?.content || '';
+  } catch (err) {
+    // Fresh agents 404 — that's the common case. Anything else should stop
+    // the import: appending to memory we couldn't read risks clobbering it.
+    if (err?.status && err.status !== 404) throw err;
+  }
+
+  const content = existing ? `${existing.trimEnd()}\n\n${imported}` : imported;
+  await client.post('/api/agents/runtime/memory/sync', {
+    mode: 'patch',
+    sourceRuntime: SOURCE_RUNTIME,
+    sections: {
+      long_term: { content, visibility: 'private' },
+    },
+  });
+
+  return { files: sources.length, bytes: content.length, appended: Boolean(existing) };
+};

package/src/lib/poller.js

@@ -0,0 +1,89 @@
+/**
+ * Event poller — polls GET /api/agents/runtime/events and forwards
+ * each event to a local handler (webhook server or callback).
+ *
+ * Used by `commonly agent connect` when running against any instance,
+ * since localhost webhooks can't receive inbound calls from remote GKE.
+ */
+
+import { createClient } from './api.js';
+
+export const startPoller = ({
+  instanceUrl,
+  token,
+  agentName,
+  instanceId = 'default',
+  intervalMs = 5000,
+  onEvent,          // async (event) => { outcome, content? }
+  onError,          // (err) => void
+}) => {
+  const client = createClient({ instance: instanceUrl, token });
+  let running = true;
+  let consecutiveErrors = 0;
+  // Stop-after-N-auth-failures: without this, a revoked token leaves the
+  // poller hammering 401s forever at 60s backoff, invisible to the user.
+  // 3 is deliberate — 1 would churn on a token-rotation race during
+  // reprovision-all; 5+ wastes rate-limit budget after the real-revoke case.
+  let consecutiveAuthErrors = 0;
+  const MAX_AUTH_ERRORS = 3;
+
+  const poll = async () => {
+    if (!running) return;
+
+    try {
+      const { events = [] } = await client.get('/api/agents/runtime/events', {
+        agentName,
+        instanceId,
+        limit: 10,
+      });
+
+      for (const event of events) {
+        let result = { outcome: 'no_action' };
+        try {
+          result = (await onEvent(event)) || { outcome: 'no_action' };
+        } catch (handlerErr) {
+          result = { outcome: 'error', reason: handlerErr.message };
+        }
+
+        // Acknowledge the event
+        try {
+          await client.post(`/api/agents/runtime/events/${event._id}/ack`, {
+            result,
+          });
+        } catch (ackErr) {
+          // Non-fatal — event will be retried
+          onError?.(new Error(`Ack failed for ${event._id}: ${ackErr.message}`));
+        }
+      }
+
+      consecutiveErrors = 0;
+      consecutiveAuthErrors = 0;
+    } catch (err) {
+      if (err?.status === 401 || err?.status === 403) {
+        consecutiveAuthErrors += 1;
+        if (consecutiveAuthErrors >= MAX_AUTH_ERRORS) {
+          onError?.(new Error(
+            `Runtime token rejected ${consecutiveAuthErrors} times in a row — stopping poller. `
+            + `The token is likely revoked.`,
+          ));
+          running = false;
+          return;
+        }
+      }
+      consecutiveErrors++;
+      onError?.(err);
+      // Back off on repeated errors (max 60s)
+      const backoff = Math.min(intervalMs * consecutiveErrors, 60_000);
+      await new Promise((r) => setTimeout(r, backoff));
+    }
+
+    if (running) setTimeout(poll, intervalMs);
+  };
+
+  // Start immediately
+  poll();
+
+  return {
+    stop: () => { running = false; },
+  };
+};