@myvillage/cli 2.8.1 → 2.9.0

package/package.json

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

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

@@ -22,6 +22,14 @@ export const DATASET_APPEND_DESCRIPTION =
   'regression provide a numeric `target`. Data stays local; provenance ' +
   'is recorded automatically.';
 
+export const DATASET_READ_DESCRIPTION =
+  'Read a LOCAL dataset on this machine: its description, columns, labels, ' +
+  'row counts, and a page of its rows (newest working set by default, or a ' +
+  'frozen version). Filter by split or label and page with offset/limit. ' +
+  'Table rows come back keyed by column name; image and sound rows come back ' +
+  'as absolute file paths (which model_predict accepts). Read-only — use ' +
+  'dataset_append to add rows.';
+
 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 ' +
@@ -38,6 +46,12 @@ export const BUILTIN_TOOL_DEFS = [
     tier: 'villager',
     builtin: true,
   },
+  {
+    name: 'dataset_read',
+    description: DATASET_READ_DESCRIPTION,
+    tier: 'villager',
+    builtin: true,
+  },
   {
     name: 'model_predict',
     description: MODEL_PREDICT_DESCRIPTION,

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

@@ -10,16 +10,63 @@
  * `myvillage dataset append` command uses — so agents and humans write
  * identically. Raw data stays local; nothing leaves the machine.
  *
- * Tool contract mirrors @myvillage-studio/dataset-schema DATASET_APPEND_TOOL.
+ * `dataset_read` is its read side: it wraps readRows() so agents can look at
+ * what's been collected (to answer questions about it, avoid duplicate
+ * appends, or feed rows to model_predict). Also local-only.
+ *
+ * Tool contracts mirror @myvillage-studio/dataset-schema DATASET_APPEND_TOOL
+ * and DATASET_READ_TOOL.
  */
 import { tool } from 'ai';
 import { z } from 'zod';
-import { appendRows, datasetExists, readManifest, ingestAsset } from '../utils/dataset-workspace.js';
-import { DATASET_APPEND_DESCRIPTION, MODEL_PREDICT_DESCRIPTION } from './builtin-tools-registry.js';
+import {
+  appendRows,
+  datasetExists,
+  readManifest,
+  readRows,
+  ingestAsset,
+  getAssetPath,
+  listDatasets,
+} from '../utils/dataset-workspace.js';
+import {
+  DATASET_APPEND_DESCRIPTION,
+  DATASET_READ_DESCRIPTION,
+  MODEL_PREDICT_DESCRIPTION,
+} from './builtin-tools-registry.js';
 import { readToolsYaml } from '../utils/local-agent.js';
 
 export { BUILTIN_TOOL_DEFS } from './builtin-tools-registry.js';
 
+const READ_DEFAULT_LIMIT = 50;
+const READ_MAX_LIMIT = 200;
+// Long text rows are clipped so one page can't blow out the model's context.
+const READ_MAX_TEXT_CHARS = 2000;
+
+/** Shape a stored row for the model: readable features, no internal noise. */
+function presentRow(slug, manifest, row) {
+  let features = row.features;
+  let truncated = false;
+  if (features && typeof features === 'object' && !Array.isArray(features) && features.path) {
+    // AssetRef → absolute path, the same form model_predict / dataset_append take
+    features = getAssetPath(slug, features.path);
+  } else if (
+    Array.isArray(features) &&
+    manifest.featureNames?.length === features.length
+  ) {
+    features = Object.fromEntries(manifest.featureNames.map((name, i) => [name, features[i]]));
+  } else if (typeof features === 'string' && features.length > READ_MAX_TEXT_CHARS) {
+    features = features.slice(0, READ_MAX_TEXT_CHARS);
+    truncated = true;
+  }
+  const out = { id: row.id, features, split: row.split };
+  if (truncated) out.truncated = true;
+  if (row.label != null) out.label = row.label;
+  if (row.target != null) out.target = row.target;
+  if (row.provenance?.source) out.source = row.provenance.source;
+  if (row.provenance?.ts) out.addedAt = row.provenance.ts;
+  return out;
+}
+
 /**
  * Gate built-ins by the SAME allowlist as the MyVillageOS platform server
  * (`allowed_tools` on whichever tools.yaml server points at a myvillageproject.ai
@@ -128,6 +175,77 @@ export function getBuiltinTools(agentName, config) {
       },
     }),
 
+    dataset_read: tool({
+      description: DATASET_READ_DESCRIPTION,
+      inputSchema: z.object({
+        datasetId: z.string().describe('Slug of the local dataset to read'),
+        version: z
+          .number()
+          .int()
+          .positive()
+          .optional()
+          .describe('Frozen version number to read; omit for the current working set'),
+        split: z.enum(['train', 'val']).optional().describe('Only rows in this split'),
+        label: z.string().optional().describe('Only rows with this class label (classification datasets)'),
+        offset: z.number().int().min(0).optional().describe('Rows to skip (default 0)'),
+        limit: z
+          .number()
+          .int()
+          .min(0)
+          .max(READ_MAX_LIMIT)
+          .optional()
+          .describe(`Rows to return (default ${READ_DEFAULT_LIMIT}, max ${READ_MAX_LIMIT}; 0 = summary only)`),
+      }),
+      execute: async ({ datasetId, version, split, label, offset = 0, limit = READ_DEFAULT_LIMIT }) => {
+        const manifest = readManifest(datasetId);
+        if (!manifest) {
+          let available = [];
+          try {
+            available = listDatasets().map((d) => d.slug);
+          } catch { /* store unavailable */ }
+          return {
+            error:
+              `Dataset "${datasetId}" not found locally.` +
+              (available.length ? ` Available: ${available.join(', ')}.` : ' No local datasets exist yet.'),
+          };
+        }
+        if (version && !manifest.versions?.some((v) => v.version === version)) {
+          const known = (manifest.versions ?? []).map((v) => v.version);
+          return {
+            error:
+              `Dataset "${datasetId}" has no version ${version}.` +
+              (known.length ? ` Frozen versions: ${known.join(', ')}.` : ' It has no frozen versions yet.'),
+          };
+        }
+        try {
+          let rows = readRows(datasetId, { version, split });
+          if (label != null) rows = rows.filter((r) => r.label === label);
+          const page = rows.slice(offset, offset + limit);
+          return {
+            ok: true,
+            datasetId: manifest.slug,
+            name: manifest.name,
+            ...(manifest.description ? { description: manifest.description } : {}),
+            modality: manifest.modality,
+            taskType: manifest.taskType,
+            labels: manifest.labels ?? [],
+            ...(manifest.featureNames ? { columns: manifest.featureNames } : {}),
+            ...(manifest.featureTypes ? { columnTypes: manifest.featureTypes } : {}),
+            stats: manifest.stats,
+            versions: (manifest.versions ?? []).map((v) => ({ version: v.version, rowCount: v.rowCount, frozenAt: v.frozenAt })),
+            reading: version ? `version ${version}` : 'working set',
+            matchingRows: rows.length,
+            offset,
+            returned: page.length,
+            hasMore: offset + page.length < rows.length,
+            rows: page.map((r) => presentRow(datasetId, manifest, r)),
+          };
+        } catch (e) {
+          return { error: e.message };
+        }
+      },
+    }),
+
     model_predict: tool({
       description: MODEL_PREDICT_DESCRIPTION,
       inputSchema: z.object({

package/src/agent-runtime/context.js

@@ -34,13 +34,14 @@ export async function gatherContext(agentConfig, lastCheckIn, recentActions = []
     }
   }
 
-  // Local Lab datasets & models, so the agent knows what it can append to /
-  // predict with (and the exact slugs to pass to dataset_append / model_predict).
+  // Local Lab datasets & models, so the agent knows what it can read / append
+  // to / predict with (and the exact slugs to pass to dataset_read /
+  // dataset_append / model_predict).
   // Local-only, synchronous file reads; tfjs is NOT loaded by listing models.
   try {
     const datasets = listDatasets();
     if (datasets.length > 0) {
-      parts.push('\nLocal datasets you can add to with dataset_append (use the slug as datasetId):');
+      parts.push('\nLocal datasets you can read with dataset_read or add to with dataset_append (use the slug as datasetId):');
       for (const d of datasets.slice(0, 25)) {
         parts.push(`- ${d.slug} — ${d.modality}/${d.taskType}, ${d.stats?.rowCount ?? 0} rows`);
       }

package/src/assets/game-toolkit/myvillage-game.js

@@ -141,7 +141,8 @@ function requestHostContext(timeoutMs) {
 // dev server.
 
 const DEFAULT_DEV_SERVER = 'https://myvillage-realtime-staging.myvillage-realtime.workers.dev';
-const CODE_ALPHABET = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789';
+// No vowels (or look-alikes), so random codes can't spell words.
+const CODE_ALPHABET = 'BCDFGHJKMNPQRSTVWXZ23456789';
 
 export class MultiplayerError extends Error {
   constructor(code, message, status) {
@@ -185,7 +186,8 @@ class Multiplayer {
     this._ticket = null;
     /** The current match (see MatchView in the platform docs), or null. */
     this.match = null;
-    this.me = { displayName: ctx ? ctx.player.displayName : options.name || 'Player ' + randomCode().slice(0, 3) };
+    // Digits only: random letters can spell words.
+    this.me = { displayName: ctx ? ctx.player.displayName : options.name || 'Player ' + (100 + Math.floor(Math.random() * 900)) };
   }
 
   // ── lobby plumbing ──
@@ -208,8 +210,14 @@ class Multiplayer {
   async quickMatch({ lobby } = {}) {
     this._requireAvailable();
     // Finished match rooms can't be reused, so dev quick match rotates rooms
-    // every 10 minutes; tabs that press it within the same window meet.
-    if (this.mode === 'dev') return this._devMatch('QUICK' + Math.floor(Date.now() / 600000).toString(36).toUpperCase(), false, lobby);
+    // every 10 minutes, and connect() steps through numbered rooms in that
+    // window past any that are finished or full. Tabs follow the same
+    // sequence, so they still meet.
+    if (this.mode === 'dev') {
+      this._devQuickBase = 'QUICK' + Math.floor(Date.now() / 600000).toString(36).toUpperCase();
+      this._devQuickTry = 0;
+      return this._devMatch(this._devQuickBase, false, lobby);
+    }
     return this._enter(await this._api('POST', `/api/v1/games/${this._game()}/matches/quick`, { platform: this._ctx.platform, lobby }));
   }
 
@@ -294,10 +302,23 @@ class Multiplayer {
   async connect() {
     this._requireAvailable();
     if (!this.match) throw new MultiplayerError('no_match', 'Host, join or quick match first.');
-    const ticket = await this._freshTicket();
     const { ArenaClient } = await import('./myvillage-realtime.js');
-    const net = new ArenaClient({ wsUrl: ticket.wsUrl, ticket: ticket.ticket });
-    await net.connect();
+    let net;
+    for (;;) {
+      const ticket = await this._freshTicket();
+      net = new ArenaClient({ wsUrl: ticket.wsUrl, ticket: ticket.ticket });
+      try {
+        await net.connect();
+        break;
+      } catch (err) {
+        // Dev quick match: that room is finished or full — try the next one.
+        const devQuick = this.mode === 'dev' && this._devQuickBase && this.match.code.startsWith(this._devQuickBase);
+        if (!devQuick || this._devQuickTry >= 20 || !/finished|full/i.test(String(err && err.message))) throw err;
+        this._devQuickTry++;
+        this._ticket = null;
+        this._devMatch(this._devQuickBase + '-' + this._devQuickTry, false, this.match.lobby);
+      }
+    }
     this._ticket = null; // single use: a reconnect fetches a fresh one
     this._net = net;
     return net;

package/src/utils/agentic-templates.js

@@ -25,7 +25,7 @@ const TOOL_GROUPS = {
   villages: ['village_search', 'village_view', 'village_create', 'village_update'],
   moments: ['moment_create', 'moment_get', 'pulse_create', 'pulse_list'],
   villagers: ['villager_me', 'villager_search', 'villager_update', 'agent_list'],
-  meetings: ['recall_send_bot', 'recall_meeting_attendance'],
+  meetings: ['recall_send_bot', 'recall_list_sessions', 'recall_meeting_attendance'],
 };
 
 // ─── Agentic App Template (Next.js) ─────────────────────────────────────────
@@ -756,7 +756,7 @@ const TOOL_GROUPS = {
   villages: ['village_search', 'village_view', 'village_create', 'village_update'],
   moments: ['moment_create', 'moment_get', 'pulse_create', 'pulse_list'],
   villagers: ['villager_me', 'villager_search', 'villager_update', 'agent_list'],
-  meetings: ['recall_send_bot', 'recall_meeting_attendance'],
+  meetings: ['recall_send_bot', 'recall_list_sessions', 'recall_meeting_attendance'],
 };
 
 // Tool groups selected during project creation