@myvillage/cli 2.12.0 → 2.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myvillage/cli",
-  "version": "2.12.0",
+  "version": "2.13.1",
   "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';
@@ -111,15 +112,24 @@ export async function agentLoop(agentName, { signal }) {
     const anthropic = createAnthropic({ apiKey });
     model = anthropic(modelId);
   }
-  const maxTokens = config.brain?.max_tokens_per_loop || 8000;
-  // Max agentic steps (one model turn + its tool executions) per loop
-  // iteration. A task like "enumerate N villagers' knowledge, then Slack each
-  // lead" needs a step per discovery wave plus the action steps; 10 was too low
-  // — the model would exhaust the budget mid-task (e.g. right after listing
-  // Slack channels but before sending). Configurable per agent via
-  // brain.max_steps_per_loop; default 25. Cost stays bounded by
-  // max_tokens_per_loop and the rate limiter regardless of this ceiling.
-  const maxSteps = config.brain?.max_steps_per_loop || 25;
+  // Output cap for each model reply (each step), not for the whole run — the AI
+  // SDK applies maxOutputTokens per generation call. Despite the config key's
+  // name it never bounded a run's total spend; the MVT balance does that.
+  const maxTokens = config.brain?.max_tokens_per_loop || 16000;
+  // Max agentic steps (one model turn + its tool executions) per run. Long,
+  // many-step tasks are the point of these agents, so by default there is NO
+  // cap: the run ends when the model finishes, not when a counter runs out. A
+  // villager can still set brain.max_steps_per_loop to bound an agent. What does
+  // end a run early is getting stuck — see stalledOnToolErrors below, which
+  // replaces the step cap as the guard against the "thrash on a broken tool"
+  // failure the old 25-step cap used to catch (slowly).
+  const maxSteps = Number(config.brain?.max_steps_per_loop) || 0;
+  // A step is one model reply plus the tools it calls. A single step that runs
+  // this long is hung (a stalled provider stream, a tool that never answers), so
+  // it's aborted and the task resumes from its last finished step.
+  const stepTimeoutMs = (Number(config.brain?.step_timeout_minutes) || 30) * 60_000;
+  const stopConditions = [stalledOnToolErrors(STALL_STEPS)];
+  if (maxSteps > 0) stopConditions.push(stepCountIs(maxSteps));
 
   // Refresh BEFORE the first MCP connect. Whoever spawned us put a snapshot of
   // MYVILLAGE_ACCESS_TOKEN in our env, and the MCP client bakes it into its
@@ -140,7 +150,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 +161,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
@@ -168,6 +182,11 @@ export async function agentLoop(agentName, { signal }) {
   let lastCheckIn = null;
   let iteration = 0;
   const recentActions = []; // Track actions across iterations to avoid duplicates
+  // A task whose run was cut short (rate limit after retries, provider outage,
+  // hung step, out of MVTs) is carried here and picked up again on the next
+  // iteration with its conversation so far, instead of being marked FAILED and
+  // losing the work. { task, messages, attempts, audit, toolCalls, tokens, startedAt, lastError }
+  let resume = null;
 
   while (!signal.aborted) {
     // Check active hours
@@ -176,9 +195,10 @@ export async function agentLoop(agentName, { signal }) {
       continue;
     }
 
-    // For manual-only agents (interval=0), only run once then exit
+    // For manual-only agents (interval=0), only run once then exit — unless a
+    // task is waiting to be resumed.
     const intervalMs = getNextCheckInMs(config.schedule);
-    if (intervalMs === 0 && iteration > 0) {
+    if (intervalMs === 0 && iteration > 0 && !resume) {
       break;
     }
 
@@ -238,11 +258,23 @@ export async function agentLoop(agentName, { signal }) {
     // Tracks whether the task's tool calls actually succeeded. The LLM
     // sometimes "summarizes" a tool error into a falsely-confident final
     // response — we don't want to trust the model's word about success.
-    const taskActionAudit = {
+    // A resumed task carries its audit forward so the verdict covers the
+    // whole task, not just the last stretch.
+    const taskActionAudit = resume?.audit || {
       actionToolsCalled: 0,
       actionToolsSucceeded: 0,
       toolErrors: [], // { tool, message }
     };
+    // The conversation so far (everything after the system prompt), kept
+    // current by onStepFinish so a failure mid-run can resume from here.
+    let runMessages = null;
+    let modelFinished = false;
+    let stepsThisRun = 0;
+    let tokensThisRun = 0;
+    const resuming = resume;
+    resume = null;
+    // Per-call record of what the agent did, attached to the task output.
+    const toolCallSummary = resuming?.toolCalls || [];
 
     try {
       // Read prompt.md fresh each iteration (villager may have edited it).
@@ -278,7 +310,9 @@ export async function agentLoop(agentName, { signal }) {
 
       // Try to pull an assigned task first. Tasks take priority over ambient
       // feed-monitoring. If nothing is queued, fall through to the default.
-      if (config.man?.village_agent_id) {
+      if (resuming) {
+        activeTask = resuming.task;
+      } else if (config.man?.village_agent_id) {
         activeTask = await pollAndClaim(config.man.village_agent_id, agentDir);
       }
 
@@ -311,7 +345,11 @@ Guidelines:
 
         context = `## TASK (id=${activeTask.id}, type=${activeTask.taskType})\n${instructionText}\n\n---\n\n## AMBIENT CONTEXT (for awareness only)\n${context}`;
 
-        logActivity(agentDir, { type: 'task_claimed', taskId: activeTask.id, taskType: activeTask.taskType });
+        if (resuming) {
+          logActivity(agentDir, { type: 'task_resumed', taskId: activeTask.id, attempt: resuming.attempts, after: resuming.lastError });
+        } else {
+          logActivity(agentDir, { type: 'task_claimed', taskId: activeTask.id, taskType: activeTask.taskType });
+        }
       }
 
       // Feed is no longer pushed into context; nothing to count here.
@@ -324,14 +362,69 @@ Guidelines:
         events: eventsFound,
       });
 
+      const conversation = resuming
+        ? [
+            ...resuming.messages,
+            {
+              role: 'user',
+              content:
+                `(Your work on this task was interrupted: ${resuming.lastError}. Pick up where you left off. ` +
+                'Everything you did above already happened, so do not repeat actions you have already taken.)',
+            },
+          ]
+        : [{ role: 'user', content: context }];
+      // Log tool calls and count activity as each step finishes, not after the
+      // whole run: a long run shows progress in the Logs panel as it goes, and a
+      // run that fails mid-way keeps the record of what it already did. Also
+      // audit action-tool success so we don't trust the model's final text about
+      // whether a task worked. `toolCallSummary` accumulates a structured
+      // per-call record that we attach to the task output so the Activity panel
+      // can show what the agent actually did — not just a tool-call count.
+      const recordStep = (step) => {
+        for (const tc of step.toolCalls || []) {
+          activity.toolCalls++;
+          if (tc.toolName === 'post_create') activity.postsCreated++;
+          if (tc.toolName === 'comment_create') activity.commentsCreated++;
+          if (tc.toolName === 'vote_cast') activity.votesGiven++;
+          collectActions(tc.toolName, tc.input ?? tc.args);
+        }
+        for (const tr of stepToolOutcomes(step)) {
+          const errored = isToolResultError(tr);
+          const resultSummary = summarizeToolResult(tr);
+          auditToolCall(taskActionAudit, tr.toolName, errored, tr);
+          toolCallSummary.push({ tool: tr.toolName, args: tr.input, result: resultSummary, ok: !errored });
+          logActivity(agentDir, { type: 'tool_call', tool: tr.toolName, args: tr.input, result: resultSummary, ok: !errored });
+        }
+      };
+
+      // Record actions for dedup in future iterations
+      const collectActions = (toolName, args) => {
+        if (toolName === 'comment_create' && args?.postId) {
+          recentActions.push({ type: 'comment', postId: args.postId, ts: new Date().toISOString() });
+        } else if (toolName === 'post_create' && args?.communitySlug) {
+          recentActions.push({ type: 'post', community: args.communitySlug, ts: new Date().toISOString() });
+        } else if (toolName === 'vote_cast' && args?.targetId) {
+          recentActions.push({ type: 'vote', targetId: args.targetId, targetType: args.targetType, ts: new Date().toISOString() });
+        }
+      };
+
       // Call LLM with tools
       // AI SDK v6 removed `maxSteps` — the loop now uses `stopWhen` with
       // a StopCondition predicate. The default is `stepCountIs(1)`, so
       // without this the model gets exactly ONE round of tool calls and
-      // returns immediately. We give it up to `maxSteps` steps (default 25,
-      // see above) so a multi-step task like "find the low-activity villagers,
-      // then message each lead" can do discover → reason → act across enough
-      // turns to actually finish, instead of stopping mid-task.
+      // returns immediately. We let it run until it finishes (or stalls, or
+      // hits a villager-set step cap — see stopConditions above) so a long
+      // task can do discover → reason → act for as many turns as it needs.
+      //
+      // Reliability for long runs: each model call retries rate limits and
+      // provider hiccups with backoff (maxRetries; 2s doubling, honoring
+      // Retry-After), a hung step is aborted after stepTimeoutMs, and Stop
+      // interrupts mid-run via abortSignal. If the run still fails, the catch
+      // below carries the task into the next iteration (see `resume`).
+      //
+      // Context: every tool result stays in the conversation, so a long run
+      // would eventually overflow the model's window. trimOldToolResults
+      // shortens older tool outputs once the conversation gets large.
       //
       // Anthropic prompt caching: we mark the system block as ephemeral so
       // everything before it (tool schemas + system prompt) is cached.
@@ -341,6 +434,7 @@ Guidelines:
       // The breakpoint is namespaced under `anthropic`, so OpenAI calls
       // silently ignore it. Cache TTL is ~5 min; agents that loop more
       // often than that stay warm and pay full price only on the first hit.
+      runMessages = conversation;
       const result = await generateText({
         model,
         messages: [
@@ -351,12 +445,30 @@ Guidelines:
               anthropic: { cacheControl: { type: 'ephemeral' } },
             },
           },
-          { role: 'user', content: context },
+          ...conversation,
         ],
         tools,
-        stopWhen: stepCountIs(maxSteps),
+        stopWhen: stopConditions,
         maxOutputTokens: maxTokens,
+        maxRetries: MODEL_MAX_RETRIES,
+        timeout: { stepMs: stepTimeoutMs },
+        abortSignal: signal,
+        prepareStep: ({ messages }) => trimOldToolResults(messages),
+        onStepFinish: (step) => {
+          stepsThisRun++;
+          tokensThisRun += step.usage?.totalTokens || 0;
+          runMessages = [...conversation, ...(step.response?.messages || [])];
+          recordStep(step);
+        },
       });
+      modelFinished = true;
+
+      if (result.steps?.length && stalledOnToolErrors(STALL_STEPS)({ steps: result.steps })) {
+        logActivity(agentDir, {
+          type: 'error',
+          error: `Stopped after ${STALL_STEPS} steps in a row where every tool call failed. Check the tool errors above.`,
+        });
+      }
 
       // Log LLM response. Cache metrics come from the Anthropic provider
       // metadata — surfacing them lets `agent logs` show whether caching is
@@ -366,9 +478,9 @@ Guidelines:
       const anthropicMeta = result.providerMetadata?.anthropic || {};
       logActivity(agentDir, {
         type: 'llm_response',
-        // Keep the full response: at ~4 chars/token, 32k chars holds a maxed-out
-        // 8k-token reply, so the Logs panel no longer clips mid-sentence.
-        text: (result.text || '').slice(0, 32000),
+        // Keep the full response: at ~4 chars/token, 64k chars holds a maxed-out
+        // 16k-token reply, so the Logs panel no longer clips mid-sentence.
+        text: (result.text || '').slice(0, 64000),
         tokensUsed: {
           prompt: result.usage?.inputTokens || 0,
           completion: result.usage?.outputTokens || 0,
@@ -378,106 +490,6 @@ Guidelines:
         },
       });
 
-      // Log tool calls and count activity. Also audit action-tool success
-      // so we don't trust the model's final text about whether a task worked.
-      // `toolCallSummary` accumulates a structured per-call record that we
-      // attach to the task output so the Activity panel can show what the
-      // agent actually did — not just a tool-call count.
-      const toolCallSummary = [];
-      if (result.steps?.length) {
-        for (const step of result.steps) {
-          if (step.toolCalls?.length) {
-            for (const tc of step.toolCalls) {
-              activity.toolCalls++;
-              if (tc.toolName === 'post_create') activity.postsCreated++;
-              if (tc.toolName === 'comment_create') activity.commentsCreated++;
-              if (tc.toolName === 'vote_cast') activity.votesGiven++;
-            }
-          }
-          if (step.toolCalls?.length && step.toolResults?.length) {
-            for (let i = 0; i < step.toolResults.length; i++) {
-              const tr = step.toolResults[i];
-              // AI SDK v6 renamed `args` → `input`. Try v6 first.
-              const args = step.toolCalls[i]?.input ?? step.toolCalls[i]?.args;
-              const errored = isToolResultError(tr);
-              const resultSummary = summarizeToolResult(tr);
-              auditToolCall(taskActionAudit, tr.toolName, errored, tr);
-              toolCallSummary.push({
-                tool: tr.toolName,
-                args,
-                result: resultSummary,
-                ok: !errored,
-              });
-              logActivity(agentDir, {
-                type: 'tool_call',
-                tool: tr.toolName,
-                args,
-                result: resultSummary,
-                ok: !errored,
-              });
-            }
-          } else if (step.toolResults?.length) {
-            for (const tr of step.toolResults) {
-              const errored = isToolResultError(tr);
-              const resultSummary = summarizeToolResult(tr);
-              auditToolCall(taskActionAudit, tr.toolName, errored, tr);
-              toolCallSummary.push({
-                tool: tr.toolName,
-                result: resultSummary,
-                ok: !errored,
-              });
-              logActivity(agentDir, {
-                type: 'tool_call',
-                tool: tr.toolName,
-                result: resultSummary,
-                ok: !errored,
-              });
-            }
-          }
-        }
-      } else if (result.toolCalls?.length) {
-        for (const tc of result.toolCalls) {
-          activity.toolCalls++;
-          if (tc.toolName === 'post_create') activity.postsCreated++;
-          if (tc.toolName === 'comment_create') activity.commentsCreated++;
-          if (tc.toolName === 'vote_cast') activity.votesGiven++;
-          // No paired result here — assume executed, can't audit.
-          const args = tc.input ?? tc.args;
-          toolCallSummary.push({
-            tool: tc.toolName,
-            args,
-            result: 'executed',
-          });
-          logActivity(agentDir, {
-            type: 'tool_call',
-            tool: tc.toolName,
-            args,
-            result: 'executed',
-          });
-        }
-      }
-
-      // Record actions for dedup in future iterations
-      const collectActions = (toolName, args) => {
-        if (toolName === 'comment_create' && args?.postId) {
-          recentActions.push({ type: 'comment', postId: args.postId, ts: new Date().toISOString() });
-        } else if (toolName === 'post_create' && args?.communitySlug) {
-          recentActions.push({ type: 'post', community: args.communitySlug, ts: new Date().toISOString() });
-        } else if (toolName === 'vote_cast' && args?.targetId) {
-          recentActions.push({ type: 'vote', targetId: args.targetId, targetType: args.targetType, ts: new Date().toISOString() });
-        }
-      };
-      if (result.steps?.length) {
-        for (const step of result.steps) {
-          for (const tc of step.toolCalls || []) {
-            collectActions(tc.toolName, tc.input ?? tc.args);
-          }
-        }
-      } else if (result.toolCalls?.length) {
-        for (const tc of result.toolCalls) {
-          collectActions(tc.toolName, tc.input ?? tc.args);
-        }
-      }
       // Keep only last 50 actions to bound memory
       if (recentActions.length > 50) recentActions.splice(0, recentActions.length - 50);
 
@@ -518,8 +530,8 @@ Guidelines:
                 toolErrors: taskActionAudit.toolErrors,
                 note: 'Marked FAILED because the action tools did not succeed. The model\'s text may claim success but the underlying tool calls errored.',
               },
-              tokensUsed: result.usage?.totalTokens || 0,
-              durationMs: Date.now() - loopStart,
+              tokensUsed: (resuming?.tokens || 0) + (result.usage?.totalTokens || 0),
+              durationMs: Date.now() - (resuming?.startedAt || loopStart),
             });
             logActivity(agentDir, {
               type: 'task_failed',
@@ -534,8 +546,8 @@ Guidelines:
                 toolCalls: toolCallSummary,
                 toolErrors: taskActionAudit.toolErrors.length > 0 ? taskActionAudit.toolErrors : undefined,
               },
-              tokensUsed: result.usage?.totalTokens || 0,
-              durationMs: Date.now() - loopStart,
+              tokensUsed: (resuming?.tokens || 0) + (result.usage?.totalTokens || 0),
+              durationMs: Date.now() - (resuming?.startedAt || loopStart),
             });
             logActivity(agentDir, { type: 'task_completed', taskId: activeTask.id });
           }
@@ -573,7 +585,7 @@ Guidelines:
     } 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');
+        console.log(`\n[MyVillage] ${err.message}.\n`);
         break;
       }
       if (err instanceof AgentPausedError) {
@@ -585,12 +597,41 @@ Guidelines:
         type: 'error',
         error: err.message,
       });
-      // If a task was in flight when we crashed, mark it FAILED so it isn't lost
-      if (activeTask && config.man?.village_agent_id) {
+      // A task cut short mid-run (rate limit that outlasted the retries, provider
+      // outage, hung step, out of MVTs) resumes on the next iteration with its
+      // conversation so far. Only after RESUME_MAX_ATTEMPTS tries in a row with
+      // no new progress is it marked FAILED. A Stop from the villager is the
+      // exception: the process is exiting, so there is nothing to resume into.
+      if (activeTask && config.man?.village_agent_id && !signal.aborted && runMessages && !modelFinished) {
+        const madeProgress = stepsThisRun > 0;
+        const attempts = madeProgress ? 1 : (resuming?.attempts || 0) + 1;
+        if (attempts <= RESUME_MAX_ATTEMPTS) {
+          resume = {
+            task: activeTask,
+            messages: runMessages,
+            attempts,
+            audit: taskActionAudit,
+            toolCalls: toolCallSummary,
+            tokens: (resuming?.tokens || 0) + tokensThisRun,
+            startedAt: resuming?.startedAt || loopStart,
+            lastError: err.message.slice(0, 300),
+          };
+          logActivity(agentDir, {
+            type: 'task_interrupted',
+            taskId: activeTask.id,
+            attempt: attempts,
+            retryInMs: resumeDelayMs(attempts),
+            error: err.message,
+          });
+        }
+      }
+      // If a task was in flight when we crashed and won't be resumed, mark it
+      // FAILED so it isn't left IN_PROGRESS forever.
+      if (activeTask && config.man?.village_agent_id && !resume) {
         try {
           await completeAgentTask(config.man.village_agent_id, activeTask.id, {
-            errorMessage: err.message,
-            durationMs: Date.now() - loopStart,
+            errorMessage: signal.aborted ? 'Stopped before the task finished' : err.message,
+            durationMs: Date.now() - (resuming?.startedAt || loopStart),
           });
           logActivity(agentDir, { type: 'task_failed', taskId: activeTask.id });
         } catch {
@@ -605,8 +646,11 @@ Guidelines:
     logActivity(agentDir, { type: 'loop_end', iteration, duration_ms: duration });
     updateHeartbeat(agentDir);
 
-    // Sleep until next interval
-    if (intervalMs > 0 && !signal.aborted) {
+    // Sleep until next interval — or, when a task is waiting to resume, only
+    // as long as its backoff (rate-limit buckets refill within a minute or two).
+    if (resume && !signal.aborted) {
+      await sleep(resumeDelayMs(resume.attempts), signal);
+    } else if (intervalMs > 0 && !signal.aborted) {
       await sleep(intervalMs, signal);
     }
   }
@@ -615,6 +659,114 @@ Guidelines:
   await cleanupMCPClients();
 }
 
+// ── Long-run settings ───────────────────────────────────
+
+// Retries per model call for retryable errors (429 rate limits, 5xx, network).
+// The AI SDK backs off 2s, 4s, 8s… and honors Retry-After, so 6 retries rides
+// out about two minutes — enough for a shared-tier per-minute bucket to refill.
+const MODEL_MAX_RETRIES = 6;
+
+// A run ends early when this many steps in a row called tools and every one of
+// them failed. That's an agent stuck on a broken tool (bad allowlist, expired
+// auth, wrong arguments), not a long task — continuing only burns MVTs.
+const STALL_STEPS = 8;
+
+// How many times an interrupted task is resumed in a row WITHOUT making
+// progress before it's marked FAILED. Any resumed run that completes a step
+// resets the count, so a long task can be interrupted any number of times.
+const RESUME_MAX_ATTEMPTS = 6;
+
+// 1, 2, 4, 8, 15, 15 min between resume attempts: about 45 min in all, long
+// enough to outlast a provider outage or for a villager to top up MVTs.
+function resumeDelayMs(attempts) {
+  return Math.min(60_000 * 2 ** Math.max(0, attempts - 1), 15 * 60_000);
+}
+
+// Once the conversation passes this size (~50k tokens at ~4 chars/token), older
+// tool results are shortened so a long run never overflows the model's context
+// window. Tool schemas and the system prompt sit on top of this, so it leaves
+// room on a 128k-token model. The newest results are always kept whole.
+const CONTEXT_TRIM_CHARS = 200_000;
+const KEEP_RECENT_TOOL_MESSAGES = 6;
+const TRIMMED_RESULT_CHARS = 400;
+
+function stalledOnToolErrors(n) {
+  return ({ steps }) => {
+    if (steps.length < n) return false;
+    return steps.slice(-n).every(step => {
+      const outcomes = stepToolOutcomes(step);
+      return outcomes.length > 0 && outcomes.every(isToolResultError);
+    });
+  };
+}
+
+// Every tool outcome in a step, successes and failures alike, paired with the
+// arguments it was called with. AI SDK v6 keeps thrown tool errors out of
+// step.toolResults (they're `tool-error` parts in step.content), and pairing
+// toolCalls[i] with toolResults[i] by index drifts as soon as one call throws.
+function stepToolOutcomes(step) {
+  if (Array.isArray(step.content)) {
+    return step.content
+      .filter(p => p.type === 'tool-result' || p.type === 'tool-error')
+      .map(p => p.type === 'tool-error'
+        ? {
+            toolName: p.toolName,
+            input: p.input,
+            output: String(p.error?.message ?? p.error ?? 'Tool failed'),
+            isError: true,
+          }
+        : {
+            toolName: p.toolName,
+            input: p.input,
+            output: p.output,
+            // MCP tools report failure as { isError: true } on their result.
+            isError: p.output?.isError === true,
+          });
+  }
+  const callsById = new Map((step.toolCalls || []).map(tc => [tc.toolCallId, tc]));
+  return (step.toolResults || []).map(tr => ({
+    ...tr,
+    input: callsById.get(tr.toolCallId)?.input ?? callsById.get(tr.toolCallId)?.args,
+  }));
+}
+
+// prepareStep hook: shortens older tool results once the conversation is large.
+// Returns {} (no change) until then, so short runs are untouched.
+function trimOldToolResults(messages) {
+  let size;
+  try { size = JSON.stringify(messages).length; } catch { return {}; }
+  if (size <= CONTEXT_TRIM_CHARS) return {};
+
+  const toolIdx = messages.flatMap((m, i) => (m.role === 'tool' ? [i] : []));
+  const trimUpTo = new Set(toolIdx.slice(0, -KEEP_RECENT_TOOL_MESSAGES));
+  if (trimUpTo.size === 0) return {};
+
+  return {
+    messages: messages.map((m, i) => {
+      if (!trimUpTo.has(i) || !Array.isArray(m.content)) return m;
+      return {
+        ...m,
+        content: m.content.map(part => {
+          if (part.type !== 'tool-result' || !part.output) return part;
+          const raw = typeof part.output.value === 'string'
+            ? part.output.value
+            : JSON.stringify(part.output.value ?? part.output);
+          if (raw.length <= TRIMMED_RESULT_CHARS + 200) return part;
+          return {
+            ...part,
+            output: {
+              type: String(part.output.type).startsWith('error') ? 'error-text' : 'text',
+              value:
+                `${raw.slice(0, TRIMMED_RESULT_CHARS)} … (earlier result shortened to keep room; ` +
+                'call the tool again if you need it in full)',
+            },
+          };
+        }),
+      };
+    }),
+  };
+}
+
 // ── Helpers ─────────────────────────────────────────────
 
 function logActivity(agentDir, entry) {
@@ -770,7 +922,7 @@ function isPausedResponse(err) {
 }
 
 class LeaseLostError extends Error {
-  constructor(message = 'Lease lost — another machine now owns this agent') {
+  constructor(message = 'Another copy of this agent took over (started on this computer or another one), so this copy stopped') {
     super(message);
     this.name = 'LeaseLostError';
     this.code = 'LEASE_LOST';

package/src/commands/agent-mcp.js

@@ -171,7 +171,7 @@ async function walkLocalWizard(connector, baseAnswers) {
       type: 'input',
       name: 'command',
       message: 'Command:',
-      default: recipe.command || 'npx',
+      default: connector.command || 'npx',
       validate: v => v.trim().length > 0 || 'command is required',
       filter: v => v.trim(),
     },
@@ -222,7 +222,7 @@ async function walkRemoteWizard(connector, baseAnswers) {
       type: 'input',
       name: 'url',
       message: 'URL:',
-      default: recipe.url || '',
+      default: connector.url || '',
       validate: v => /^https?:\/\//i.test((v || '').trim()) || 'must start with http:// or https://',
       filter: v => v.trim(),
     },

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));
+}

package/src/utils/agent-scaffolder.js

@@ -165,7 +165,7 @@ function generateAgentConfig({ name, displayName, description, checkInInterval,
     brain: {
       provider: provider || 'anthropic',
       model: model || (provider === 'openai' ? 'gpt-4o' : 'claude-sonnet-4-5-20250929'),
-      max_tokens_per_loop: 8000,
+      max_tokens_per_loop: 16000,
       fallback_provider: null,
     },