@myvillage/cli 1.85.2 → 1.87.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myvillage/cli",
-  "version": "1.85.2",
+  "version": "1.87.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,236 @@
+/**
+ * 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 to the control plane with a
+ * `machine:runner` API key (MYVILLAGE_MACHINE_KEY) sent as `x-api-key`. Spawned
+ * agent daemons still use the owner's OAuth token (from ~/.myvillage/
+ * credentials.json), which must be provisioned on the machine once.
+ */
+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 });
+    fs.writeFileSync(RUNNER_STATE_FILE, JSON.stringify(state, null, 2));
+  } 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;
+    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)}`);
+  return json.data.id;
+}
+
+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 = {}) {
+  const machineKey = opts.machineKey || process.env.MYVILLAGE_MACHINE_KEY;
+  if (!machineKey) {
+    throw new Error('MYVILLAGE_MACHINE_KEY is required (a machine:runner API key). Set the env var or pass --key.');
+  }
+
+  const cpForRegister = makeClient(machineKey, null);
+  log(`registering machine "${opts.name || os.hostname()}" (${process.platform}/${process.arch})…`);
+  const machineId = await register(cpForRegister, opts);
+  persistRunnerState({ machineId, name: opts.name || os.hostname(), registeredAt: new Date().toISOString() });
+  log(`registered as machine ${machineId}`);
+
+  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/agent-local.js

@@ -333,12 +333,19 @@ export async function agentRecipesListCommand() {
 
 // ── Start Agent ─────────────────────────────────────────
 
-export async function agentStartCommand(name) {
+export async function agentStartCommand(name, options = {}) {
   if (!isAuthenticated()) {
     console.log(chalk.red('  \u2717 Authentication required. Run \'myvillage login\' first.'));
     return;
   }
 
+  // Organizational village tags for this agent (grouping/filtering only \u2014 no
+  // access effect). Accept either a pre-parsed array (if a caller passes one)
+  // or a comma-separated string from the --village flag.
+  const associatedVillages = Array.isArray(options.village)
+    ? options.village.map(v => String(v).trim()).filter(Boolean)
+    : (options.village || '').split(',').map(v => v.trim()).filter(Boolean);
+
   if (!agentExists(name)) {
     // Check whether the agent exists server-side under this handle. If so,
     // this is a "different machine" situation \u2014 point them at `agent pull`
@@ -453,7 +460,7 @@ export async function agentStartCommand(name) {
           archetypes: [],
           greeting: '',
           starterPrompts: [],
-          associatedVillages: [],
+          associatedVillages,
           specialInstructions: null,
           agentProfileId: agent.id,
         });
@@ -512,7 +519,7 @@ export async function agentStartCommand(name) {
         archetypes: [],
         greeting: '',
         starterPrompts: [],
-        associatedVillages: [],
+        associatedVillages,
         specialInstructions: null,
         agentProfileId: agentConfig.man.agent_id,
       });

package/src/commands/agent.js

@@ -27,7 +27,7 @@ async function resolveAgentHandle(handle) {
 
 // ── Commands ─────────────────────────────────────────
 
-export async function agentCommand(handle) {
+export async function agentCommand(handle, options = {}) {
   if (!isAuthenticated()) {
     console.log(chalk.red('  \u2717 Authentication required. Run \'myvillage login\' first.'));
     return;
@@ -46,7 +46,8 @@ export async function agentCommand(handle) {
   const spinner = villageSpinner('Loading remote agents...').start();
 
   try {
-    const result = await listMyAgents();
+    // --village filters remote agents by an associated village id (organizational).
+    const result = await listMyAgents(options.village ? { village: options.village } : {});
     spinner.stop();
 
     const agents = result.data || result;

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,
@@ -440,6 +441,7 @@ export function run() {
   const agentCmd = program
     .command('agent [handle]')
     .description('List your agents, or view an agent by handle')
+    .option('--village <id>', 'Filter agents by associated village ID')
     .action(agentCommand);
 
   agentCmd
@@ -510,6 +512,7 @@ export function run() {
   agentCmd
     .command('start <name>')
     .description('Start a local agent daemon')
+    .option('--village <ids>', 'Comma-separated village IDs to tag this agent with (organizational only; does not change access)')
     .action(agentStartCommand);
 
   agentCmd
@@ -991,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();
 }

package/src/utils/api.js

@@ -290,8 +290,14 @@ export async function createAgent(data) {
   return response.data;
 }
 
-export async function listMyAgents(params = {}) {
-  const client = getNetworkClient();
+export async function listMyAgents(options = {}) {
+  const client = getNetworkClient();
+  // Pass through recognized query params. `village` filters by an associated
+  // village id (organizational grouping only); existing callers may also pass
+  // excludeSystem / unlinked etc., so spread the rest through unchanged.
+  const { village, ...rest } = options;
+  const params = { ...rest };
+  if (village) params.village = village;
   const response = await client.get('/agents/my', { params });
   return response.data;
 }

package/src/utils/formatters.js

@@ -398,6 +398,8 @@ export function formatAgentList(agents) {
     if (agent.agentCategory && agent.agentCategory !== 'NETWORK' && agent.schedule) {
       console.log(`  ${chalk.dim('  ')}${chalk.dim(`Schedule: ${agent.schedule}`)}`);
     }
+    const villages = Array.isArray(agent.associatedVillages) ? agent.associatedVillages.filter(Boolean) : [];
+    console.log(`  ${chalk.dim('  ')}${chalk.dim(`Villages: ${villages.length ? villages.join(', ') : '—'}`)}`);
     console.log('');
   }
 }