@myvillage/cli 2.9.0 → 2.12.0

package/package.json

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

package/src/agent-runtime/builtin-tools-registry.js

@@ -30,6 +30,13 @@ export const DATASET_READ_DESCRIPTION =
   'as absolute file paths (which model_predict accepts). Read-only — use ' +
   'dataset_append to add rows.';
 
+export const DATASET_SPLIT_DESCRIPTION =
+  'Shuffle a LOCAL dataset\'s working set into training rows and validation ' +
+  '(held-back checking) rows in one step. `valPercent` (default 20) is the share ' +
+  'held back; classification datasets split each label evenly so every group ' +
+  'is checked. Replaces any split already set by hand. Use it before training, ' +
+  'or after adding many rows. Data stays local.';
+
 export const MODEL_PREDICT_DESCRIPTION =
   'Run a prediction with a LOCAL trained model on this machine. `input` is ' +
   'text (words models), the values of one table row as a list in column ' +
@@ -52,6 +59,12 @@ export const BUILTIN_TOOL_DEFS = [
     tier: 'villager',
     builtin: true,
   },
+  {
+    name: 'dataset_split',
+    description: DATASET_SPLIT_DESCRIPTION,
+    tier: 'villager',
+    builtin: true,
+  },
   {
     name: 'model_predict',
     description: MODEL_PREDICT_DESCRIPTION,
@@ -59,3 +72,25 @@ export const BUILTIN_TOOL_DEFS = [
     builtin: true,
   },
 ];
+
+/** One line telling an agent what a local model is for and what it takes. */
+export function describeLocalModel(m) {
+  const f = m.featurization ?? {};
+  const modality = f.modality ?? m.modality;
+  let takes;
+  if (modality === 'image') takes = 'a local image file path (.jpg/.png)';
+  else if (modality === 'audio') takes = 'a local .wav file path';
+  else if (modality === 'text') takes = 'some writing';
+  else if (Array.isArray(f.columns)) {
+    takes = 'a table row with ' + f.columns.map((c) => `${JSON.stringify(c.name)} (${c.type})`).join(', ');
+  } else if (Array.isArray(m.featureNames) && m.featureNames.length) {
+    takes = 'a table row of numbers: ' + m.featureNames.map((n) => JSON.stringify(n)).join(', ');
+  } else {
+    takes = `a list of ${m.inputDim ?? 'some'} numbers`;
+  }
+  const gives =
+    m.taskType === 'classification' && Array.isArray(m.labels) && m.labels.length
+      ? `sorts it into: ${m.labels.join(', ')}`
+      : 'gives back a number';
+  return `- "${m.slug}" (${m.name}): takes ${takes}; ${gives}.`;
+}

package/src/agent-runtime/builtin-tools.js

@@ -14,6 +14,9 @@
  * what's been collected (to answer questions about it, avoid duplicate
  * appends, or feed rows to model_predict). Also local-only.
  *
+ * `dataset_split` wraps splitRows() — the same engine as
+ * `myvillage dataset split` — to deal rows into train / val in one write.
+ *
  * Tool contracts mirror @myvillage-studio/dataset-schema DATASET_APPEND_TOOL
  * and DATASET_READ_TOOL.
  */
@@ -24,6 +27,7 @@ import {
   datasetExists,
   readManifest,
   readRows,
+  splitRows,
   ingestAsset,
   getAssetPath,
   listDatasets,
@@ -31,8 +35,12 @@ import {
 import {
   DATASET_APPEND_DESCRIPTION,
   DATASET_READ_DESCRIPTION,
+  DATASET_SPLIT_DESCRIPTION,
   MODEL_PREDICT_DESCRIPTION,
+  describeLocalModel,
 } from './builtin-tools-registry.js';
+import { readAgentModels } from '../utils/agent-models.js';
+import { readModelManifest as readModelManifestSync } from '../utils/model-workspace.js';
 import { readToolsYaml } from '../utils/local-agent.js';
 
 export { BUILTIN_TOOL_DEFS } from './builtin-tools-registry.js';
@@ -91,11 +99,21 @@ function applyBuiltinAllowlist(builtins, agentName) {
   if (!Array.isArray(allowed)) return builtins;
   const filtered = {};
   for (const [name, t] of Object.entries(builtins)) {
-    if (allowed.includes(name)) filtered[name] = t;
+    // model_predict is granted by the agent's `models:` list, not this allowlist.
+    if (name === 'model_predict' || allowed.includes(name)) filtered[name] = t;
   }
   return filtered;
 }
 
+/** model_predict's description, naming the models this agent was given. */
+function modelPredictDescription(slugs, readModelManifest) {
+  const lines = slugs.map((slug) => {
+    const m = readModelManifest(slug);
+    return m ? describeLocalModel(m) : `- "${slug}": not on this computer yet.`;
+  });
+  return `${MODEL_PREDICT_DESCRIPTION} Use one whenever its job matches what you are doing. The models you can use (the quoted slug is the modelId):\n${lines.join('\n')}`;
+}
+
 /**
  * Build the native built-in tools for an agent.
  * @param {string} agentName
@@ -103,6 +121,8 @@ function applyBuiltinAllowlist(builtins, agentName) {
  * @returns {Record<string, object>} AI SDK tools keyed by tool name
  */
 export function getBuiltinTools(agentName, config) {
+  // Models are granted per agent, like tools: only the ones in its tools.yaml.
+  const grantedModels = readAgentModels(agentName);
   const all = {
     dataset_append: tool({
       description: DATASET_APPEND_DESCRIPTION,
@@ -246,8 +266,33 @@ export function getBuiltinTools(agentName, config) {
       },
     }),
 
+    dataset_split: tool({
+      description: DATASET_SPLIT_DESCRIPTION,
+      inputSchema: z.object({
+        datasetId: z.string().describe('Slug of the local dataset to split'),
+        valPercent: z
+          .number()
+          .min(0)
+          .max(90)
+          .optional()
+          .describe('Percent of rows held back for validation (default 20)'),
+        seed: z.number().int().optional().describe('Seed for a repeatable shuffle'),
+      }),
+      execute: async ({ datasetId, valPercent = 20, seed }) => {
+        if (!datasetExists(datasetId)) {
+          return { error: `Dataset "${datasetId}" not found locally.` };
+        }
+        try {
+          const r = splitRows(datasetId, { valPercent, seed });
+          return { ok: true, datasetId: r.datasetId, valPercent: r.valPercent, moved: r.moved, stats: r.stats };
+        } catch (e) {
+          return { error: e.message };
+        }
+      },
+    }),
+
     model_predict: tool({
-      description: MODEL_PREDICT_DESCRIPTION,
+      description: modelPredictDescription(grantedModels, readModelManifestSync),
       inputSchema: z.object({
         modelId: z.string().describe('Slug of the local trained model'),
         input: z
@@ -263,6 +308,13 @@ export function getBuiltinTools(agentName, config) {
           ),
       }),
       execute: async ({ modelId, input }) => {
+        if (!grantedModels.includes(modelId)) {
+          return {
+            error:
+              `This agent hasn't been given the model "${modelId}". ` +
+              `It can use: ${grantedModels.join(', ')}.`,
+          };
+        }
         try {
           // Lazy-load the model/tfjs code so agent startup stays light — tfjs
           // only loads the first time an agent actually predicts.
@@ -286,5 +338,6 @@ export function getBuiltinTools(agentName, config) {
       },
     }),
   };
+  if (grantedModels.length === 0) delete all.model_predict;
   return applyBuiltinAllowlist(all, agentName);
 }

package/src/agent-runtime/context.js

@@ -13,8 +13,10 @@
 
 import { listDatasets } from '../utils/dataset-workspace.js';
 import { listModels } from '../utils/model-workspace.js';
+import { describeLocalModel } from './builtin-tools-registry.js';
+import { readAgentModels } from '../utils/agent-models.js';
 
-export async function gatherContext(agentConfig, lastCheckIn, recentActions = []) {
+export async function gatherContext(agentConfig, lastCheckIn, recentActions = [], agentName = agentConfig?.name) {
   const parts = [];
 
   parts.push(`Current time: ${new Date().toISOString()}`);
@@ -50,13 +52,12 @@ export async function gatherContext(agentConfig, lastCheckIn, recentActions = []
     /* no local datasets / store unavailable — skip */
   }
   try {
-    const models = listModels();
+    // Only the models this agent was given (its tools.yaml `models:` list).
+    const granted = new Set(agentName ? readAgentModels(agentName) : []);
+    const models = listModels().filter((m) => granted.has(m.slug));
     if (models.length > 0) {
-      parts.push('\nLocal models you can run with model_predict (use the slug as modelId):');
-      for (const m of models.slice(0, 25)) {
-        const labels = m.labels?.length ? ` → ${m.labels.join('/')}` : '';
-        parts.push(`- ${m.slug} — ${m.modality}/${m.taskType}${labels}`);
-      }
+      parts.push('\nModels you can run with model_predict (the quoted slug is the modelId). Use one whenever its job matches what you are doing:');
+      for (const m of models.slice(0, 25)) parts.push(describeLocalModel(m));
     }
   } catch {
     /* no local models / store unavailable — skip */

package/src/agent-runtime/loop.js

@@ -286,7 +286,7 @@ export async function agentLoop(agentName, { signal }) {
       // no longer auto-fetched here — the agent pulls them on demand via its
       // tools — so these activity counters stay at 0 unless a future signal
       // repopulates them.
-      const contextResult = await gatherContext(config, lastCheckIn, recentActions);
+      const contextResult = await gatherContext(config, lastCheckIn, recentActions, agentName);
       let context = contextResult.text;
       const eventsFound = 0;
 
@@ -665,6 +665,7 @@ const ACTION_TOOLS = new Set([
   'moment_create',
   'pulse_create',
   'dataset_append',
+  'dataset_split',
   'agent_join_community',
   'agent_leave_community',
   'wallet_send',

package/src/agent-runtime/runner.js

@@ -27,6 +27,7 @@ import { refreshAccessToken } from '../utils/api.js';
 import { listLocalAgents, readAgentConfig, getAgentDir, writeAgentConfig } from '../utils/local-agent.js';
 import { startDaemon, stopDaemon, isDaemonRunning, getDaemonInfo } from './daemon.js';
 import { shipLogsOnce, forgetLogCursor } from './log-shipper.js';
+import { writeSyncedModel } from '../utils/agent-models.js';
 
 const RUNNER_STATE_FILE = path.join(os.homedir(), '.myvillage', 'runner.json');
 const DEFAULT_HEARTBEAT_MS = 20_000;
@@ -176,6 +177,16 @@ async function syncAgentConfig(ctx, assignment) {
     fs.writeFileSync(path.join(agentDir, 'tools.yaml'), c.toolsYaml);
   }
 
+  // The trained models this agent was given travel with its config.
+  if (c.models && typeof c.models === 'object') {
+    for (const [slug, entry] of Object.entries(c.models)) {
+      const result = writeSyncedModel(slug, entry);
+      if (result === 'written') log(`synced model ${slug} for ${name}`);
+      else if (result === 'kept-local') log(`kept this machine's own model ${slug} for ${name}`);
+      else if (result === 'invalid') log(`skipped model ${slug} for ${name}: its files didn't check out`);
+    }
+  }
+
   // Compose agent.config.yaml from server-known identity + published schedule
   // and brain, preserving anything already set locally that the control plane
   // does not own.

package/src/commands/dataset.js

@@ -21,6 +21,7 @@ import {
   freezeVersion,
   deleteRow,
   updateRow,
+  splitRows,
 } from '../utils/dataset-workspace.js';
 
 // ── create ─────────────────────────────────────────────
@@ -250,6 +251,23 @@ export async function datasetRowUpdateCommand(options) {
   }
 }
 
+// ── split ──────────────────────────────────────────────
+
+export async function datasetSplitCommand(slug, options) {
+  try {
+    const result = splitRows(slug, { valPercent: options.val, seed: options.seed });
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    success(`Split ${slug}: ${100 - result.valPercent}% train / ${result.valPercent}% val`);
+    info(`  total: ${result.stats.rowCount} (train ${result.stats.bySplit.train} / val ${result.stats.bySplit.val}) · ${result.moved} rows moved`);
+  } catch (e) {
+    error(e.message);
+    process.exitCode = 1;
+  }
+}
+
 // ── helpers ────────────────────────────────────────────
 
 function readRowsFromFile(path) {

package/src/index.js

@@ -143,6 +143,7 @@ import {
   datasetFreezeCommand,
   datasetRowDeleteCommand,
   datasetRowUpdateCommand,
+  datasetSplitCommand,
 } from './commands/dataset.js';
 import {
   modelTrainCommand,
@@ -1054,6 +1055,14 @@ export function run() {
     .option('--json', 'Output raw JSON')
     .action(datasetRowUpdateCommand);
 
+  datasetCmd
+    .command('split <slug>')
+    .description('Shuffle the working set into train and val (each label split evenly)')
+    .option('--val <percent>', 'Percent of rows held back to check the model (0-90)', '20')
+    .option('--seed <n>', 'Seed for a repeatable shuffle')
+    .option('--json', 'Output raw JSON')
+    .action(datasetSplitCommand);
+
   // ── Studio Lab: model training (local, TF.js CPU engine) ───────────────
   const modelCmd = program
     .command('model')

package/src/utils/agent-models.js

@@ -0,0 +1,88 @@
+/**
+ * The trained models an agent may use, and the files that carry them between
+ * machines.
+ *
+ * An agent's models are granted like its tools: a `models:` list of local
+ * model slugs in its tools.yaml. No list means no models. Because tools.yaml
+ * is published verbatim to the control plane, the list follows the agent to
+ * any machine; the model files themselves travel in the published config's
+ * `models` field (see bundleAgentModels / writeSyncedModel).
+ *
+ * A model a machine trained itself is never overwritten by a synced copy. A
+ * synced copy is marked with `.synced-hash`, so the runner only replaces what
+ * it put there.
+ */
+import { createHash } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { readToolsYaml } from './local-agent.js';
+import { getModelDir, modelExists } from './model-workspace.js';
+
+const MODEL_FILES = ['manifest.json', 'model.json', 'weights.b64'];
+const SYNCED_MARKER = '.synced-hash';
+const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,127}$/;
+
+/** Slugs listed under `models:` in an agent's tools.yaml (deduped, in order). */
+export function readAgentModels(agentName) {
+  const list = readToolsYaml(agentName)?.models;
+  if (!Array.isArray(list)) return [];
+  return [...new Set(list.filter((s) => typeof s === 'string' && SLUG_RE.test(s)))];
+}
+
+function hashFiles(files) {
+  const h = createHash('sha256');
+  for (const f of MODEL_FILES) h.update(f).update('\0').update(files[f]).update('\0');
+  return h.digest('hex');
+}
+
+/**
+ * The files for each of an agent's models that exist on this machine, keyed by
+ * slug: { hash, files: { 'manifest.json', 'model.json', 'weights.b64' } }.
+ */
+export function bundleAgentModels(agentName) {
+  const out = {};
+  for (const slug of readAgentModels(agentName)) {
+    if (!modelExists(slug)) continue;
+    const dir = getModelDir(slug);
+    try {
+      const files = Object.fromEntries(MODEL_FILES.map((f) => [f, readFileSync(join(dir, f), 'utf-8')]));
+      out[slug] = { hash: hashFiles(files), files };
+    } catch {
+      /* half-written or partly deleted model: skip it */
+    }
+  }
+  return out;
+}
+
+/**
+ * Write a model that arrived with an agent's config. Returns what happened:
+ * 'written', 'current' (already this version), 'kept-local' (this machine
+ * trained its own model with that name), or 'invalid'.
+ */
+export function writeSyncedModel(slug, entry) {
+  if (!SLUG_RE.test(slug) || !entry || typeof entry.files !== 'object') return 'invalid';
+  const files = entry.files;
+  if (!MODEL_FILES.every((f) => typeof files[f] === 'string' && files[f].length > 0)) return 'invalid';
+  const hash = hashFiles(files);
+  if (entry.hash && entry.hash !== hash) return 'invalid';
+  try {
+    if (JSON.parse(files['manifest.json']).slug !== slug) return 'invalid';
+  } catch {
+    return 'invalid';
+  }
+
+  const dir = getModelDir(slug);
+  const markerPath = join(dir, SYNCED_MARKER);
+  if (modelExists(slug)) {
+    if (!existsSync(markerPath)) return 'kept-local';
+    if (readFileSync(markerPath, 'utf-8').trim() === hash) return 'current';
+  }
+  mkdirSync(dir, { recursive: true });
+  // Weights first and the manifest last: a model counts as present once its
+  // manifest exists, so a half-finished write never looks like a whole model.
+  writeFileSync(join(dir, 'weights.b64'), files['weights.b64']);
+  writeFileSync(join(dir, 'model.json'), files['model.json']);
+  writeFileSync(join(dir, 'manifest.json'), files['manifest.json']);
+  writeFileSync(markerPath, hash);
+  return 'written';
+}

package/src/utils/dataset-workspace.js

@@ -494,6 +494,68 @@ export function updateRow(slug, rowId, updates = {}) {
   return { datasetId: slug, updated: merged.id, stats: manifest.stats };
 }
 
+// ── Split the working set into train / val ─────────────
+
+/** Small seeded random (mulberry32), so a --seed split is repeatable. */
+function seededRandom(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function shuffle(items, rand) {
+  for (let i = items.length - 1; i > 0; i--) {
+    const j = Math.floor(rand() * (i + 1));
+    [items[i], items[j]] = [items[j], items[i]];
+  }
+  return items;
+}
+
+/**
+ * Re-deal every working-set row into train or val in one write. Rows are
+ * shuffled, and for classification each label is split on its own, so every
+ * group gets its fair share of val rows (a label with 2+ rows always keeps at
+ * least one of each). Records the ratio in manifest.splitConfig.
+ * @param {string} slug
+ * @param {{valPercent?:number, seed?:number}} opts  valPercent 0–90, default 20
+ * @returns {{datasetId:string, valPercent:number, moved:number, stats:object}}
+ */
+export function splitRows(slug, { valPercent = 20, seed } = {}) {
+  const manifest = readManifest(slug);
+  if (!manifest) throw new Error(`Dataset "${slug}" not found.`);
+  const pct = Number(valPercent);
+  if (!Number.isFinite(pct) || pct < 0 || pct > 90) {
+    throw new Error('The share held back for checking must be between 0 and 90 percent.');
+  }
+  const rows = readRows(slug);
+  if (rows.length === 0) throw new Error('This dataset has no rows to split yet.');
+  const rand = seed != null && seed !== '' ? seededRandom(Number(seed)) : Math.random;
+
+  const groups = new Map();
+  for (const row of rows) {
+    const key = manifest.taskType === 'classification' ? (row.label ?? '') : '';
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(row);
+  }
+  const before = new Map(rows.map((r) => [r.id, r.split]));
+  for (const group of groups.values()) {
+    let nVal = Math.round((group.length * pct) / 100);
+    if (pct > 0 && group.length >= 2) nVal = Math.min(Math.max(nVal, 1), group.length - 1);
+    shuffle([...group], rand).forEach((row, i) => {
+      row.split = i < nVal ? 'val' : 'train';
+    });
+  }
+  const moved = rows.filter((r) => before.get(r.id) !== r.split).length;
+  manifest.splitConfig = { ...(manifest.splitConfig || {}), trainRatio: 1 - pct / 100 };
+  writeWorkingSet(slug, manifest, rows);
+  return { datasetId: slug, valPercent: pct, moved, stats: manifest.stats };
+}
+
 // ── Freeze a version ───────────────────────────────────
 
 /**