@myvillage/cli 2.12.0 → 2.13.0

package/package.json

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

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

@@ -73,8 +73,19 @@ export const BUILTIN_TOOL_DEFS = [
   },
 ];
 
-/** One line telling an agent what a local model is for and what it takes. */
-export function describeLocalModel(m) {
+/** Longest example input shown to an agent, so a model's description stays short. */
+const MAX_EXAMPLE_CHARS = 400;
+
+/**
+ * Tell an agent what a local model is for, what it takes, and what it gives
+ * back, so it can decide whether the model fits the job.
+ *
+ * `extras` come from the dataset the model learned from: `labelNames` (the
+ * villager's names for each label id, e.g. waiting → "Spam and Junk"),
+ * `learnedFrom` (the dataset's description) and `example` (one training input,
+ * so the agent sends text shaped the same way).
+ */
+export function describeLocalModel(m, extras = {}) {
   const f = m.featurization ?? {};
   const modality = f.modality ?? m.modality;
   let takes;
@@ -88,9 +99,18 @@ export function describeLocalModel(m) {
   } else {
     takes = `a list of ${m.inputDim ?? 'some'} numbers`;
   }
+  const names = extras.labelNames ?? {};
+  const label = (l) => (names[l] && names[l] !== l ? `"${l}" (${names[l]})` : `"${l}"`);
   const gives =
     m.taskType === 'classification' && Array.isArray(m.labels) && m.labels.length
-      ? `sorts it into: ${m.labels.join(', ')}`
+      ? `sorts it into: ${m.labels.map(label).join(', ')}`
       : 'gives back a number';
-  return `- "${m.slug}" (${m.name}): takes ${takes}; ${gives}.`;
+  const lines = [`- "${m.slug}" (${m.name}): takes ${takes}; ${gives}.`];
+  if (extras.learnedFrom) lines.push(`  Learned from: ${extras.learnedFrom}`);
+  if (extras.example != null && modality !== 'image' && modality !== 'audio') {
+    let ex = typeof extras.example === 'string' ? extras.example : JSON.stringify(extras.example);
+    if (ex.length > MAX_EXAMPLE_CHARS) ex = ex.slice(0, MAX_EXAMPLE_CHARS) + '…';
+    lines.push(`  Send input shaped like this training example: ${JSON.stringify(ex)}`);
+  }
+  return lines.join('\n');
 }

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

@@ -37,10 +37,8 @@ import {
   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 { readAgentModels, describeAgentModel, modelDatasetExtras } from '../utils/agent-models.js';
 import { readToolsYaml } from '../utils/local-agent.js';
 
 export { BUILTIN_TOOL_DEFS } from './builtin-tools-registry.js';
@@ -106,11 +104,8 @@ function applyBuiltinAllowlist(builtins, agentName) {
 }
 
 /** 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.`;
-  });
+function modelPredictDescription(slugs) {
+  const lines = slugs.map(describeAgentModel);
   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')}`;
 }
 
@@ -292,7 +287,7 @@ export function getBuiltinTools(agentName, config) {
     }),
 
     model_predict: tool({
-      description: modelPredictDescription(grantedModels, readModelManifestSync),
+      description: modelPredictDescription(grantedModels),
       inputSchema: z.object({
         modelId: z.string().describe('Slug of the local trained model'),
         input: z
@@ -331,7 +326,10 @@ export function getBuiltinTools(agentName, config) {
           const { predictWithModel } = await import('../utils/model-trainer.js');
           const record = readModelManifest(modelId);
           const model = await loadModel(modelId);
-          return predictWithModel(model, record, input);
+          const result = await predictWithModel(model, record, input);
+          // Name the label the way the villager named it (e.g. "Spam and Junk").
+          const name = result?.label != null ? modelDatasetExtras(record).labelNames?.[result.label] : undefined;
+          return name && name !== result.label ? { ...result, labelName: name } : result;
         } catch (e) {
           return { error: e.message };
         }

package/src/agent-runtime/context.js

@@ -13,8 +13,7 @@
 
 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';
+import { readAgentModels, describeAgentModel } from '../utils/agent-models.js';
 
 export async function gatherContext(agentConfig, lastCheckIn, recentActions = [], agentName = agentConfig?.name) {
   const parts = [];
@@ -57,7 +56,7 @@ export async function gatherContext(agentConfig, lastCheckIn, recentActions = []
     const models = listModels().filter((m) => granted.has(m.slug));
     if (models.length > 0) {
       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));
+      for (const m of models.slice(0, 25)) parts.push(describeAgentModel(m.slug));
     }
   } catch {
     /* no local models / store unavailable — skip */

package/src/agent-runtime/loop.js

@@ -10,6 +10,7 @@ import { join } from 'path';
 import { homedir } from 'os';
 import { getMCPTools, cleanupMCPClients } from './mcp-client.js';
 import { getBuiltinTools } from './builtin-tools.js';
+import { readAgentModels } from '../utils/agent-models.js';
 import { gatherContext } from './context.js';
 import { isWithinActiveHours, getNextCheckInMs } from './scheduler.js';
 import { parse as parseYaml } from 'yaml';
@@ -140,7 +141,8 @@ export async function agentLoop(agentName, { signal }) {
     const result = await getMCPTools(agentDir, config);
     tools = result.tools;
     // Merge native built-in tools (in-process; no MCP server). e.g. dataset_append.
-    Object.assign(tools, getBuiltinTools(agentName, config));
+    const builtins = getBuiltinTools(agentName, config);
+    Object.assign(tools, builtins);
     const servers = result.servers;
     const totalTools = Object.keys(tools).length;
     const failed = servers.filter(s => s.status === 'failed');
@@ -150,6 +152,9 @@ export async function agentLoop(agentName, { signal }) {
       model: modelId,
       totalTools,
       servers,
+      // Named so the log shows what the agent could use, models included.
+      builtinTools: Object.keys(builtins),
+      models: readAgentModels(agentName),
     });
 
     // Surface failed MCP connections as an error event too, so they show up

package/src/utils/agent-models.js

@@ -16,10 +16,13 @@ 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';
+import { getModelDir, modelExists, readModelManifest } from './model-workspace.js';
+import { readManifest as readDatasetManifest, readRows } from './dataset-workspace.js';
+import { describeLocalModel } from '../agent-runtime/builtin-tools-registry.js';
 
 const MODEL_FILES = ['manifest.json', 'model.json', 'weights.b64'];
 const SYNCED_MARKER = '.synced-hash';
+const ABOUT_FILE = 'about.json';
 const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,127}$/;
 
 /** Slugs listed under `models:` in an agent's tools.yaml (deduped, in order). */
@@ -46,7 +49,9 @@ export function bundleAgentModels(agentName) {
     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 };
+      const manifest = JSON.parse(files['manifest.json']);
+      // What the dataset says about the model, since its dataset stays here.
+      out[slug] = { hash: hashFiles(files), files, about: modelDatasetExtras(manifest) };
     } catch {
       /* half-written or partly deleted model: skip it */
     }
@@ -75,7 +80,10 @@ export function writeSyncedModel(slug, entry) {
   const markerPath = join(dir, SYNCED_MARKER);
   if (modelExists(slug)) {
     if (!existsSync(markerPath)) return 'kept-local';
-    if (readFileSync(markerPath, 'utf-8').trim() === hash) return 'current';
+    if (readFileSync(markerPath, 'utf-8').trim() === hash) {
+      writeAbout(dir, entry.about); // label names can change without retraining
+      return 'current';
+    }
   }
   mkdirSync(dir, { recursive: true });
   // Weights first and the manifest last: a model counts as present once its
@@ -84,5 +92,50 @@ export function writeSyncedModel(slug, entry) {
   writeFileSync(join(dir, 'model.json'), files['model.json']);
   writeFileSync(join(dir, 'manifest.json'), files['manifest.json']);
   writeFileSync(markerPath, hash);
+  writeAbout(dir, entry.about);
   return 'written';
 }
+
+/** The synced copy of what a model's dataset says about it (see modelDatasetExtras). */
+function writeAbout(dir, about) {
+  if (about && typeof about === 'object') writeFileSync(join(dir, ABOUT_FILE), JSON.stringify(about));
+}
+
+/**
+ * What the model's dataset adds to its description: the villager's names for
+ * its labels, what the dataset is, and one training input as an example.
+ * Falls back to the copy synced with the model, else empty; the model still
+ * works without it.
+ */
+export function modelDatasetExtras(m) {
+  try {
+    const ds = m.datasetSlug ? readDatasetManifest(m.datasetSlug) : null;
+    if (!ds) return syncedAbout(m.slug);
+    let example;
+    try {
+      example = readRows(m.datasetSlug, { split: 'train', limit: 1 })[0]?.features;
+    } catch {
+      /* no rows to show */
+    }
+    return { labelNames: ds.labelNames ?? undefined, learnedFrom: ds.description || undefined, example };
+  } catch {
+    return {};
+  }
+}
+
+/** On a machine without the dataset: what came with the synced model. */
+function syncedAbout(slug) {
+  try {
+    const about = JSON.parse(readFileSync(join(getModelDir(slug), ABOUT_FILE), 'utf-8'));
+    return about && typeof about === 'object' ? about : {};
+  } catch {
+    return {};
+  }
+}
+
+/** One model as an agent should see it (see describeLocalModel). */
+export function describeAgentModel(slug) {
+  const m = readModelManifest(slug);
+  if (!m) return `- "${slug}": not on this computer yet.`;
+  return describeLocalModel(m, modelDatasetExtras(m));
+}