@commonlyai/cli 0.1.31 → 0.1.34

package/README.md

@@ -24,4 +24,6 @@ Requires Node 20+. No build step.
 node --experimental-vm-modules node_modules/.bin/jest --no-coverage
 ```
 
-70 tests as of 2026-04-15.
+Instance-selection tests use distinct persisted `savedAt` values and both insertion orders.
+Keep active-instance precedence separate from the newest-match fallback; back-to-back
+`saveInstance` calls can share a millisecond and hide a broken selection branch.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.31",
+  "version": "0.1.34",
   "license": "Apache-2.0",
-  "description": "The Commonly CLI \u2014 connect agents, manage pods, iterate fast",
+  "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",
   "main": "./src/index.js",
   "bin": {

package/src/commands/daemon.js

@@ -6,10 +6,20 @@
  * later slices; this command never reads an agent runtime credential.
  */
 
-import { hostname } from 'os';
+import { hostname, homedir } from 'os';
+import { spawn } from 'child_process';
+import { existsSync, mkdirSync, openSync } from 'fs';
+import { join } from 'path';
 import { createClient } from '../lib/api.js';
 import { getToken, resolveInstanceUrl } from '../lib/config.js';
 import { loadDaemonRecord, saveDaemonRecord } from '../lib/daemon-store.js';
+import {
+  createDaemonSupervisor,
+  DEFAULT_HEARTBEAT_MS,
+  DEFAULT_POLL_MS,
+} from '../lib/daemon-supervisor.js';
+import { loadAgentToken, saveAgentToken } from './agent.js';
+import { getAdapter } from '../lib/adapters/index.js';
 
 const requireDaemonRecord = () => {
   const record = loadDaemonRecord();
@@ -80,6 +90,20 @@ export const getDaemonMachineStatus = async ({ client }) => {
   return response?.machine || null;
 };
 
+// The adapter names a binary on THIS machine — the one fact the server cannot
+// know (same reasoning as `agent run`'s env bootstrap). A server-declared
+// preference is honored when that CLI is installed; otherwise probe the known
+// ones in order.
+export const resolveAdapterForRuntime = async (runtime, registry = { getAdapter }) => {
+  const candidates = [runtime?.adapter, 'claude', 'codex'].filter(Boolean);
+  for (const name of candidates) {
+    const adapter = registry.getAdapter(name);
+    // eslint-disable-next-line no-await-in-loop
+    if (adapter && await adapter.detect()) return name;
+  }
+  return null;
+};
+
 export const registerDaemon = (program) => {
   const daemon = program.command('daemon').description('Manage the local Commonly daemon');
 
@@ -147,6 +171,58 @@ Examples:
       }
     });
 
+  // ── run (ADR-026 Phase 2, slice 2) ────────────────────────────────────────
+  daemon
+    .command('run')
+    .description('Run the resident supervisor: adopt requested agents, keep bound agents running, report per-agent state')
+    .option('--poll <ms>', 'Work-list poll interval in ms', String(DEFAULT_POLL_MS))
+    .option('--heartbeat <ms>', 'Heartbeat interval in ms', String(DEFAULT_HEARTBEAT_MS))
+    .action(async (opts) => {
+      try {
+        const record = requireDaemonRecord();
+        const client = createClient({ instance: record.instanceUrl, token: record.daemonToken });
+        const logsDir = join(homedir(), '.commonly', 'logs', 'daemon');
+        if (!existsSync(logsDir)) mkdirSync(logsDir, { recursive: true });
+        const stampLog = (line) => console.log(`${new Date().toISOString()} ${line}`);
+
+        const supervisor = createDaemonSupervisor({
+          record,
+          client,
+          // One child per agent, logging to its own file. The child is the
+          // ordinary `commonly agent run <name>` — the daemon is its
+          // supervisor, never its replacement (D6).
+          spawnChild: (agentName) => {
+            const out = openSync(join(logsDir, `${agentName}.log`), 'a');
+            return spawn(process.execPath, [process.argv[1], 'agent', 'run', agentName], {
+              stdio: ['ignore', out, out],
+            });
+          },
+          loadToken: loadAgentToken,
+          saveToken: saveAgentToken,
+          resolveAdapter: (runtime) => resolveAdapterForRuntime(runtime),
+          log: stampLog,
+        });
+
+        stampLog(`daemon supervising for ${record.machineName} — poll ${opts.poll}ms, heartbeat ${opts.heartbeat}ms (ctrl+c to stop)`);
+        await supervisor.tick();
+        await supervisor.heartbeat();
+        const pollTimer = setInterval(() => supervisor.tick(), Number(opts.poll) || DEFAULT_POLL_MS);
+        const heartbeatTimer = setInterval(() => supervisor.heartbeat(), Number(opts.heartbeat) || DEFAULT_HEARTBEAT_MS);
+        const shutdown = () => {
+          stampLog('daemon stopping — terminating supervised agents');
+          clearInterval(pollTimer);
+          clearInterval(heartbeatTimer);
+          supervisor.stop();
+          process.exit(0);
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+      } catch (error) {
+        console.error(`Daemon run failed: ${error.message}`);
+        process.exitCode = 1;
+      }
+    });
+
   daemon
     .command('status')
     .description('Show the server-derived liveness of this machine')

package/src/lib/daemon-supervisor.js

@@ -0,0 +1,239 @@
+/**
+ * ADR-026 Phase 2, slice 2: the resident supervision loop behind
+ * `commonly daemon run`.
+ *
+ * The server's work list (GET /api/agent-binding/assigned) is the source of
+ * truth (D2): a row `requested` gets adopted (the D3 CAS — the server refuses
+ * the loser of a race cleanly), a row `bound` gets provisioned (token file)
+ * and supervised (a `commonly agent run <name>` child), and a supervised
+ * agent that leaves the list gets stopped. Per-agent state rides every
+ * machine heartbeat (D5).
+ *
+ * D6 discipline: a replacement child is only ever scheduled from the previous
+ * child's 'exit' event — there is no code path that spawns a second runner
+ * for an agent whose child has not exited.
+ *
+ * All side effects (client, spawn, token file I/O, adapter detection, timers)
+ * are injected so the loop's decisions are testable without processes.
+ */
+
+export const DEFAULT_POLL_MS = 30_000;
+export const DEFAULT_HEARTBEAT_MS = 30_000;
+export const BACKOFF_BASE_MS = 5_000;
+export const BACKOFF_MAX_MS = 60_000;
+
+export const backoffMs = (restarts) => Math.min(
+  BACKOFF_MAX_MS,
+  BACKOFF_BASE_MS * 2 ** Math.max(0, Math.min(restarts, 10)),
+);
+
+const identityKey = (agentName, instanceId) => `${agentName} ${instanceId || 'default'}`;
+
+export const createDaemonSupervisor = ({
+  record,
+  client,
+  spawnChild, // (agentName) => child emitting 'exit'; must expose .kill()
+  loadToken, // (agentName) => token record | null
+  saveToken, // (agentName, record) => void
+  resolveAdapter, // async (runtime) => adapter name for THIS machine
+  log = () => {},
+  setTimeoutFn = setTimeout,
+  clearTimeoutFn = clearTimeout,
+}) => {
+  // key → { agentName, instanceId, child, state, restarts, backoffTimer, desired }
+  const seats = new Map();
+  let stopped = false;
+
+  const agentStates = () => Array.from(seats.values()).map((s) => ({
+    agentName: s.agentName,
+    instanceId: s.instanceId,
+    state: s.state,
+    restarts: s.restarts,
+  }));
+
+  const startChild = (seat) => {
+    if (stopped || !seat.desired || seat.child) return;
+    seat.child = spawnChild(seat.agentName);
+    seat.state = 'running';
+    log(`[${seat.agentName}] supervising (restarts so far: ${seat.restarts})`);
+    seat.child.on('exit', (code) => {
+      seat.child = null;
+      if (stopped || !seat.desired) {
+        seat.state = 'stopped';
+        return;
+      }
+      seat.state = code === 0 ? 'stopped' : 'crashed';
+      seat.restarts += 1;
+      const delay = backoffMs(seat.restarts - 1);
+      log(`[${seat.agentName}] exited (code ${code}) — respawn in ${Math.round(delay / 1000)}s`);
+      seat.backoffTimer = setTimeoutFn(() => {
+        seat.backoffTimer = null;
+        startChild(seat);
+      }, delay);
+    });
+  };
+
+  const stopSeat = (seat) => {
+    seat.desired = false;
+    if (seat.backoffTimer) {
+      clearTimeoutFn(seat.backoffTimer);
+      seat.backoffTimer = null;
+    }
+    if (seat.child) {
+      log(`[${seat.agentName}] no longer assigned here — stopping`);
+      seat.child.kill('SIGTERM');
+    } else {
+      seat.state = 'stopped';
+    }
+  };
+
+  // The server-declared runtime config carries the owner's model choice; the
+  // adapter reads it from the token record's environment (claude: --model).
+  const environmentFor = (row) => (
+    row.runtime?.model ? { model: String(row.runtime.model) } : null
+  );
+
+  // Ensure ~/.commonly/tokens/<name>.json exists so `agent run` can boot.
+  // The mint refuses to clobber an existing token (409 token_exists); the
+  // binding to THIS machine is the owner's explicit takeover choice (D3), so
+  // that refusal is answered with rotate:true — loudly.
+  // Returns 'ready' | 'changed' (record updated — the seat must restart to
+  // load it) | false.
+  const ensureToken = async (row) => {
+    const existing = loadToken(row.agentName);
+    if (existing) {
+      // A model changed in the UI reaches the seat here: update the record,
+      // and let the caller restart the child (`agent run` reads its record
+      // once at boot). A row with NO declared model leaves the record alone —
+      // never strip an operator's hand-set environment.
+      const wanted = environmentFor(row);
+      if (wanted && existing.environment?.model !== wanted.model) {
+        saveToken(row.agentName, { ...existing, environment: { ...(existing.environment || {}), ...wanted } });
+        log(`[${row.agentName}] model changed to ${wanted.model} — restarting the seat to load it`);
+        return 'changed';
+      }
+      return 'ready';
+    }
+    const body = { agentName: row.agentName, instanceId: row.instanceId };
+    let minted;
+    try {
+      minted = await client.post('/api/agent-binding/runtime-token', body);
+    } catch (error) {
+      if (error?.status === 409 && error?.body?.code === 'token_exists') {
+        log(`[${row.agentName}] a runtime token exists elsewhere — rotating it to this machine (the old token stops working)`);
+        try {
+          minted = await client.post('/api/agent-binding/runtime-token', { ...body, rotate: true });
+        } catch (rotateError) {
+          log(`[${row.agentName}] token rotation failed: ${rotateError.message}`);
+          return false;
+        }
+      } else {
+        log(`[${row.agentName}] token mint failed: ${error.message}`);
+        return false;
+      }
+    }
+    if (!minted?.token) {
+      log(`[${row.agentName}] mint returned no token — skipping`);
+      return false;
+    }
+    const adapter = await resolveAdapter(row.runtime || null);
+    if (!adapter) {
+      log(`[${row.agentName}] no usable CLI adapter on this machine — install claude or codex, or attach manually`);
+      return false;
+    }
+    const environment = environmentFor(row);
+    saveToken(row.agentName, {
+      agentName: row.agentName,
+      instanceId: row.instanceId,
+      runtimeToken: minted.token,
+      instanceUrl: record.instanceUrl,
+      podId: row.podIds?.[0] || null,
+      adapter,
+      ...(environment ? { environment } : {}),
+    });
+    log(`[${row.agentName}] provisioned runtime token (adapter: ${adapter}${environment ? `, model: ${environment.model}` : ''})`);
+    return 'ready';
+  };
+
+  const tick = async () => {
+    if (stopped) return;
+    let assigned;
+    try {
+      assigned = await client.get('/api/agent-binding/assigned');
+    } catch (error) {
+      log(`work-list fetch failed: ${error.message}`);
+      return;
+    }
+    const rows = Array.isArray(assigned?.agents) ? assigned.agents : [];
+
+    const bound = [];
+    for (const row of rows) {
+      if (row.state === 'requested') {
+        try {
+          // eslint-disable-next-line no-await-in-loop
+          await client.post('/api/agent-binding/adopt', {
+            agentName: row.agentName, instanceId: row.instanceId,
+          });
+          log(`[${row.agentName}] adopted onto this machine`);
+          bound.push(row);
+        } catch (error) {
+          // A clean CAS refusal (409) means another machine won — drop it.
+          log(`[${row.agentName}] adopt refused: ${error.message}`);
+        }
+      } else {
+        bound.push(row);
+      }
+    }
+
+    const desiredKeys = new Set();
+    for (const row of bound) {
+      const key = identityKey(row.agentName, row.instanceId);
+      desiredKeys.add(key);
+      let seat = seats.get(key);
+      if (!seat) {
+        seat = {
+          agentName: row.agentName,
+          instanceId: row.instanceId || 'default',
+          child: null,
+          state: 'stopped',
+          restarts: 0,
+          backoffTimer: null,
+          desired: true,
+        };
+        seats.set(key, seat);
+      }
+      seat.desired = true;
+      // eslint-disable-next-line no-await-in-loop
+      const ready = await ensureToken(row);
+      if (ready === 'changed' && seat.child) {
+        // desired stays true, so the exit handler respawns with the updated
+        // record — the restart path IS the D6 path, no second spawner.
+        seat.child.kill('SIGTERM');
+      } else if (ready && !seat.child && !seat.backoffTimer) {
+        startChild(seat);
+      }
+    }
+
+    for (const [key, seat] of seats) {
+      if (!desiredKeys.has(key) && seat.desired) stopSeat(seat);
+    }
+  };
+
+  const heartbeat = async () => {
+    if (stopped) return;
+    try {
+      await client.post(`/api/machines/${record.machineDbId}/heartbeat`, { agents: agentStates() });
+    } catch (error) {
+      log(`heartbeat failed: ${error.message}`);
+    }
+  };
+
+  const stop = () => {
+    stopped = true;
+    for (const seat of seats.values()) stopSeat(seat);
+  };
+
+  return {
+    tick, heartbeat, stop, agentStates,
+  };
+};