@myvillage/cli 1.86.0 → 1.88.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myvillage/cli",
-  "version": "1.86.0",
+  "version": "1.88.0",
   "description": "MyVillageOS CLI for community developers",
   "type": "module",
   "bin": {

package/src/agent-runtime/loop.js

@@ -522,6 +522,11 @@ Guidelines:
       // Send server-side heartbeat
       if (config.man?.agent_id) {
         try {
+          // Fleet fencing: when this agent was launched under a runner lease,
+          // report the machine + lease epoch so the server can reject us (409
+          // LEASE_LOST) if another machine has taken over. Absent otherwise.
+          const machineId = process.env.MYVILLAGE_MACHINE_ID;
+          const leaseEpoch = process.env.MYVILLAGE_LEASE_EPOCH;
           await postAgentHeartbeat(config.man.agent_id, {
             postsCreated: activity.postsCreated,
             commentsCreated: activity.commentsCreated,
@@ -531,13 +536,21 @@ Guidelines:
             tokensUsed: result.usage?.totalTokens || 0,
             durationMs: Date.now() - loopStart,
             activitySummary: { feedItemsRead, mentionsFound },
+            ...(machineId ? { machineId } : {}),
+            ...(leaseEpoch !== undefined ? { leaseEpoch: Number(leaseEpoch) } : {}),
           });
         } catch (err) {
           if (isPausedResponse(err)) throw new AgentPausedError();
+          if (isLeaseLostResponse(err)) throw new LeaseLostError();
           logActivity(agentDir, { type: 'error', error: 'Failed to send server heartbeat' });
         }
       }
     } catch (err) {
+      if (err instanceof LeaseLostError) {
+        logActivity(agentDir, { type: 'lease_lost', message: err.message });
+        console.log('\n[MyVillage] Lease lost — another machine now owns this agent. Exiting.\n');
+        break;
+      }
       if (err instanceof AgentPausedError) {
         logActivity(agentDir, { type: 'agent_paused', message: err.message });
         console.log('\n[MyVillage] This agent has been paused by an admin. Exiting.\n');
@@ -730,6 +743,18 @@ function isPausedResponse(err) {
   return err?.response?.status === 409 && err?.response?.data?.code === 'AGENT_PAUSED';
 }
 
+class LeaseLostError extends Error {
+  constructor(message = 'Lease lost — another machine now owns this agent') {
+    super(message);
+    this.name = 'LeaseLostError';
+    this.code = 'LEASE_LOST';
+  }
+}
+
+function isLeaseLostResponse(err) {
+  return err?.response?.status === 409 && err?.response?.data?.code === 'LEASE_LOST';
+}
+
 // Pull up to 5 pending tasks and claim the first one we can win the race for.
 // Returns the claimed task or null. Errors are swallowed and logged — the loop
 // should keep running on transient backend issues. A pause response (409

package/src/agent-runtime/runner.js

@@ -0,0 +1,314 @@
+/**
+ * Headless fleet runner.
+ *
+ * One per machine (Raspberry Pi, DGX Spark, office Mac, or Studio in-process).
+ * Registers the machine, then loops: heartbeat (renew leases + report observed
+ * + pull assignments) → reconcile local agent daemons to match. Single-active is
+ * enforced by the control-plane lease; this runner only starts an agent after it
+ * acquires the lease, and stops+releases anything it holds that is no longer
+ * assigned-and-running here.
+ *
+ * Auth model: the runner authenticates as a machine with a `machine:runner` API
+ * key sent as `x-api-key`. That key is normally provisioned automatically — on
+ * first start the runner registers using the signed-in user's OAuth token and
+ * the control plane mints + returns a machine-scoped credential, which is saved
+ * to ~/.myvillage/runner.json (0600) and reused thereafter. So a machine that
+ * has run `myvillage login` (or Studio) never needs a hand-made key; supplying
+ * MYVILLAGE_MACHINE_KEY / --key stays supported for unattended provisioning.
+ * Spawned agent daemons still use the owner's OAuth token from
+ * ~/.myvillage/credentials.json.
+ */
+import os from 'os';
+import fs from 'fs';
+import path from 'path';
+import { getConfig } from '../utils/config.js';
+import { getAccessToken } from '../utils/auth.js';
+import { listLocalAgents, readAgentConfig } from '../utils/local-agent.js';
+import { startDaemon, stopDaemon, isDaemonRunning, getDaemonInfo } from './daemon.js';
+
+const RUNNER_STATE_FILE = path.join(os.homedir(), '.myvillage', 'runner.json');
+const DEFAULT_HEARTBEAT_MS = 20_000;
+const LEASE_TTL_SECONDS = 90;
+
+function log(msg, extra) {
+  const line = `[runner] ${new Date().toISOString()} ${msg}`;
+  if (extra !== undefined) console.log(line, extra);
+  else console.log(line);
+}
+
+function collectMetadata() {
+  return {
+    hostname: os.hostname(),
+    loadavg: os.loadavg(),
+    totalmem: os.totalmem(),
+    freemem: os.freemem(),
+    cpus: os.cpus().length,
+    uptimeSec: Math.round(os.uptime()),
+  };
+}
+
+function persistRunnerState(state) {
+  try {
+    fs.mkdirSync(path.dirname(RUNNER_STATE_FILE), { recursive: true });
+    // 0600: the file holds this machine's credential.
+    fs.writeFileSync(RUNNER_STATE_FILE, JSON.stringify(state, null, 2), { mode: 0o600 });
+    try { fs.chmodSync(RUNNER_STATE_FILE, 0o600); } catch { /* best-effort */ }
+  } catch { /* best-effort */ }
+}
+
+export function readRunnerState() {
+  try {
+    return JSON.parse(fs.readFileSync(RUNNER_STATE_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// ── Control-plane client (machine principal via x-api-key) ───────────────────
+
+function makeClient(machineKey, machineId) {
+  const { networkBaseUrl } = getConfig();
+  return async function cp(pathname, { method = 'GET', body } = {}) {
+    const headers = { 'Content-Type': 'application/json', 'x-api-key': machineKey };
+    if (machineId) headers['X-Machine-Id'] = machineId;
+    return request(networkBaseUrl, pathname, method, body, headers);
+  };
+}
+
+/**
+ * One-shot client authenticated as the signed-in *user* (OAuth bearer). Used
+ * only to register a machine and receive its minted credential.
+ */
+function makeUserClient() {
+  const { networkBaseUrl } = getConfig();
+  const token = getAccessToken();
+  if (!token) return null;
+  return async function cp(pathname, { method = 'GET', body } = {}) {
+    const headers = { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` };
+    return request(networkBaseUrl, pathname, method, body, headers);
+  };
+}
+
+async function request(networkBaseUrl, pathname, method, body, headers) {
+  const res = await fetch(`${networkBaseUrl}${pathname}`, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let json;
+  try { json = text ? JSON.parse(text) : {}; } catch { json = { raw: text }; }
+  return { status: res.status, ok: res.ok, json };
+}
+
+// ── Local agent indexing ─────────────────────────────────────────────────────
+
+// Map control-plane agentProfileId -> local agent { name, config } via the
+// `man.agent_id` binding in each local agent.config.yaml.
+function indexLocalAgentsByProfileId() {
+  const map = new Map();
+  for (const a of listLocalAgents()) {
+    let cfg;
+    try { cfg = readAgentConfig(a.name); } catch { continue; }
+    const profileId = cfg?.man?.agent_id;
+    if (profileId) map.set(profileId, { name: a.name, config: cfg });
+  }
+  return map;
+}
+
+function startAgent(name, config, machineId, leaseEpoch) {
+  const token = getAccessToken();
+  if (token) process.env.MYVILLAGE_ACCESS_TOKEN = token;
+  if (config.man?.agent_id) process.env.MYVILLAGE_AGENT_ID = config.man.agent_id;
+  if (config.man?.village_agent_id) process.env.MYVILLAGE_VILLAGE_AGENT_ID = config.man.village_agent_id;
+  process.env.MYVILLAGE_MACHINE_ID = machineId;
+  process.env.MYVILLAGE_LEASE_EPOCH = String(leaseEpoch);
+  const pid = startDaemon(name);
+  // Clear the per-agent fencing vars so they don't bleed into the next spawn.
+  delete process.env.MYVILLAGE_LEASE_EPOCH;
+  return pid;
+}
+
+// ── Registration + reconcile ─────────────────────────────────────────────────
+
+async function register(cp, opts) {
+  const body = {
+    name: opts.name || os.hostname(),
+    kind: opts.kind,
+    platform: process.platform,
+    arch: process.arch,
+    agentVersion: opts.agentVersion,
+    capacity: opts.capacity,
+    metadata: collectMetadata(),
+  };
+  const { ok, status, json } = await cp('/machines', { method: 'POST', body });
+  if (!ok) throw new Error(`register failed (${status}): ${JSON.stringify(json)}`);
+  // machineKey is present only on the user-auth path (minted once, server-side).
+  return { machineId: json.data.id, machineKey: json.data.machineKey ?? null };
+}
+
+/**
+ * Resolve this machine's credential without asking a human for one:
+ *   1. an explicit --key / MYVILLAGE_MACHINE_KEY (unattended provisioning)
+ *   2. the credential saved on a previous start (~/.myvillage/runner.json)
+ *   3. otherwise register as the signed-in user; the control plane mints one
+ *
+ * Returns { machineId, machineKey }.
+ */
+async function resolveMachineIdentity(opts) {
+  const explicitKey = opts.machineKey || process.env.MYVILLAGE_MACHINE_KEY || null;
+  const saved = readRunnerState();
+
+  if (explicitKey) {
+    const { machineId } = await register(makeClient(explicitKey, null), opts);
+    persistRunnerState({
+      machineId,
+      machineKey: explicitKey,
+      name: opts.name || os.hostname(),
+      registeredAt: new Date().toISOString(),
+    });
+    return { machineId, machineKey: explicitKey };
+  }
+
+  if (saved?.machineKey) {
+    // Re-register with the stored credential so name/metadata/version refresh.
+    const { machineId } = await register(makeClient(saved.machineKey, null), opts);
+    persistRunnerState({ ...saved, machineId, name: opts.name || saved.name, registeredAt: new Date().toISOString() });
+    return { machineId, machineKey: saved.machineKey };
+  }
+
+  const userClient = makeUserClient();
+  if (!userClient) {
+    throw new Error(
+      'Not signed in. Run `myvillage login` on this machine (or pass --key with a machine:runner API key).',
+    );
+  }
+  const { machineId, machineKey } = await register(userClient, opts);
+  if (!machineKey) {
+    throw new Error('The control plane did not return a machine credential. Update the backend and retry.');
+  }
+  persistRunnerState({
+    machineId,
+    machineKey,
+    name: opts.name || os.hostname(),
+    registeredAt: new Date().toISOString(),
+  });
+  return { machineId, machineKey };
+}
+
+async function reconcileOnce(ctx) {
+  const observed = [];
+  for (const [profileId, lease] of ctx.leases) {
+    observed.push({
+      agentProfileId: profileId,
+      observedState: isDaemonRunning(lease.name) ? 'RUNNING' : 'STOPPED',
+      pid: getDaemonInfo(lease.name)?.pid ?? null,
+    });
+  }
+
+  const hb = await ctx.cp(`/machines/${ctx.machineId}/heartbeat`, {
+    method: 'POST',
+    body: { status: 'ONLINE', metadata: collectMetadata(), agentVersion: ctx.agentVersion, agents: observed },
+  });
+  if (!hb.ok) {
+    log(`heartbeat failed (${hb.status})`, hb.json?.error);
+    return;
+  }
+  const assignments = hb.json.data.assignments || [];
+  const local = indexLocalAgentsByProfileId();
+
+  const desiredRunning = assignments.filter((a) => a.desiredState === 'RUNNING');
+  const desiredIds = new Set(desiredRunning.map((a) => a.agentProfileId));
+
+  // Adopt agents already running under our ownership after a runner restart.
+  for (const a of assignments) {
+    if (
+      a.ownerMachineId === ctx.machineId &&
+      !ctx.leases.has(a.agentProfileId) &&
+      local.has(a.agentProfileId) &&
+      isDaemonRunning(local.get(a.agentProfileId).name)
+    ) {
+      ctx.leases.set(a.agentProfileId, { name: local.get(a.agentProfileId).name, epoch: a.leaseEpoch });
+      log(`adopted running agent ${local.get(a.agentProfileId).name} (epoch ${a.leaseEpoch})`);
+    }
+  }
+
+  // Start desired-running agents we don't yet own+run here.
+  for (const a of desiredRunning) {
+    const entry = local.get(a.agentProfileId);
+    if (!entry) {
+      log(`assigned agent ${a.handle || a.agentProfileId} has no local config on this machine — skipping (provision it first)`);
+      continue;
+    }
+    if (ctx.leases.has(a.agentProfileId) && isDaemonRunning(entry.name)) continue;
+
+    const lease = await ctx.cp(`/agents/${a.agentProfileId}/lease`, {
+      method: 'POST',
+      body: { action: 'acquire', ttlSeconds: LEASE_TTL_SECONDS },
+    });
+    if (!lease.ok) {
+      log(`could not acquire lease for ${entry.name} (${lease.json?.code || lease.status}) — held elsewhere, will retry`);
+      continue;
+    }
+    const epoch = lease.json.data.leaseEpoch;
+    const pid = startAgent(entry.name, entry.config, ctx.machineId, epoch);
+    ctx.leases.set(a.agentProfileId, { name: entry.name, epoch });
+    log(`started ${entry.name} (pid ${pid}, epoch ${epoch})`);
+  }
+
+  // Stop + release anything we hold that is no longer desired-running here.
+  for (const [profileId, lease] of [...ctx.leases]) {
+    if (desiredIds.has(profileId)) continue;
+    try { stopDaemon(lease.name); } catch { /* best-effort */ }
+    await ctx.cp(`/agents/${profileId}/lease`, { method: 'POST', body: { action: 'release' } });
+    ctx.leases.delete(profileId);
+    log(`stopped + released ${lease.name} (no longer assigned here)`);
+  }
+}
+
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    if (signal) signal.addEventListener('abort', () => { clearTimeout(t); resolve(); }, { once: true });
+  });
+}
+
+export async function runRunner(opts = {}) {
+  log(`registering machine "${opts.name || os.hostname()}" (${process.platform}/${process.arch})…`);
+  const { machineId, machineKey } = await resolveMachineIdentity(opts);
+  log(`registered as machine ${machineId}`);
+
+  // Record our pid so Studio (or `runner status`) can tell whether this
+  // machine's runner is alive, and stop it. Cleared on exit.
+  const markRunning = (pid) => {
+    const s = readRunnerState() || {};
+    persistRunnerState({ ...s, pid, startedAt: pid ? new Date().toISOString() : undefined });
+  };
+  markRunning(process.pid);
+  const clearPid = () => { try { markRunning(null); } catch { /* best-effort */ } };
+  process.on('exit', clearPid);
+
+  const ctx = {
+    cp: makeClient(machineKey, machineId),
+    machineId,
+    agentVersion: opts.agentVersion,
+    leases: new Map(),
+  };
+
+  const controller = new AbortController();
+  const shutdown = () => { log('shutting down (agents keep running; leases will expire for failover)'); controller.abort(); };
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+
+  const intervalMs = opts.intervalMs || DEFAULT_HEARTBEAT_MS;
+  log(`reconcile loop every ${Math.round(intervalMs / 1000)}s (lease TTL ${LEASE_TTL_SECONDS}s)`);
+  while (!controller.signal.aborted) {
+    try {
+      await reconcileOnce(ctx);
+    } catch (err) {
+      log('reconcile error', err?.message || err);
+    }
+    if (!controller.signal.aborted) await sleep(intervalMs, controller.signal);
+  }
+  log('runner stopped');
+}

package/src/commands/runner.js

@@ -0,0 +1,40 @@
+/**
+ * `myvillage runner` — headless fleet runner commands.
+ */
+import { createRequire } from 'module';
+import { runRunner, readRunnerState } from '../agent-runtime/runner.js';
+
+function getCliVersion() {
+  try {
+    const require = createRequire(import.meta.url);
+    return require('../../package.json').version;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function runnerStartCommand(options = {}) {
+  try {
+    await runRunner({
+      name: options.name,
+      kind: options.kind ? String(options.kind).toUpperCase() : undefined,
+      capacity: options.capacity ? parseInt(options.capacity, 10) : undefined,
+      intervalMs: options.interval ? parseInt(options.interval, 10) * 1000 : undefined,
+      machineKey: options.key,
+      agentVersion: getCliVersion(),
+    });
+  } catch (err) {
+    console.error(`[runner] ${err.message}`);
+    process.exit(1);
+  }
+}
+
+export function runnerStatusCommand() {
+  const state = readRunnerState();
+  if (!state) {
+    console.log('No runner has registered on this machine yet. Run `myvillage runner start`.');
+    return;
+  }
+  console.log(`Machine:    ${state.name} (${state.machineId})`);
+  console.log(`Registered: ${state.registeredAt}`);
+}

package/src/index.js

@@ -72,6 +72,7 @@ import {
   agentRememberCommand,
   agentRecipesListCommand,
 } from './commands/agent-local.js';
+import { runnerStartCommand, runnerStatusCommand } from './commands/runner.js';
 import {
   agentRegisterClientCommand,
   agentListClientsCommand,
@@ -993,5 +994,23 @@ export function run() {
     .option('--json', 'Output raw JSON')
     .action(modelPredictCommand);
 
+  // ── Fleet runner ───────────────────────────────────────
+  const runnerCmd = program
+    .command('runner')
+    .description('Fleet runner: register this machine and run its assigned agents');
+  runnerCmd
+    .command('start')
+    .description('Register this machine and run agents assigned to it')
+    .option('--name <name>', 'Machine name (default: hostname)')
+    .option('--kind <kind>', 'Machine kind: laptop|mac|pi|spark|cloud|other')
+    .option('--capacity <n>', 'Soft cap on concurrently-run agents')
+    .option('--interval <sec>', 'Reconcile/heartbeat interval in seconds (default 20)')
+    .option('--key <apiKey>', 'machine:runner API key (or set MYVILLAGE_MACHINE_KEY)')
+    .action(runnerStartCommand);
+  runnerCmd
+    .command('status')
+    .description("Show this machine's runner registration")
+    .action(runnerStatusCommand);
+
   program.parse();
 }