@myvillage/cli 2.13.0 → 2.13.2

package/package.json

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

package/src/agent-runtime/loop.js

@@ -112,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
@@ -173,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
@@ -181,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;
     }
 
@@ -243,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).
@@ -283,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);
       }
 
@@ -316,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.
@@ -329,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.
@@ -346,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: [
@@ -356,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
@@ -371,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,
@@ -383,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);
 
@@ -523,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',
@@ -539,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 });
           }
@@ -578,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) {
@@ -590,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 {
@@ -610,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);
     }
   }
@@ -620,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) {
@@ -775,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/agent-runtime/runner.js

@@ -24,10 +24,10 @@ import path from 'path';
 import { getConfig } from '../utils/config.js';
 import { getAccessToken, isTokenExpired } from '../utils/auth.js';
 import { refreshAccessToken } from '../utils/api.js';
-import { listLocalAgents, readAgentConfig, getAgentDir, writeAgentConfig } from '../utils/local-agent.js';
+import { listLocalAgents, readAgentConfig, getAgentDir } 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';
+import { writePublishedAgentConfig, readSyncedVersion } from '../utils/agent-config-sync.js';
 
 const RUNNER_STATE_FILE = path.join(os.homedir(), '.myvillage', 'runner.json');
 const DEFAULT_HEARTBEAT_MS = 20_000;
@@ -128,20 +128,6 @@ async function request(networkBaseUrl, pathname, method, body, headers) {
 
 // ── Config sync (materialise an assigned agent from the control plane) ───────
 
-// Records which published config version this machine last wrote, so we only
-// re-write files when the definition actually changed.
-function syncedVersionPath(agentDir) {
-  return path.join(agentDir, '.config-version');
-}
-
-function readSyncedVersion(agentDir) {
-  try {
-    return Number(fs.readFileSync(syncedVersionPath(agentDir), 'utf8').trim()) || 0;
-  } catch {
-    return 0;
-  }
-}
-
 /**
  * Write an assigned agent's files from its published definition, creating the
  * agent directory if this machine has never run it. Returns true when the agent
@@ -167,53 +153,12 @@ async function syncAgentConfig(ctx, assignment) {
     log(`could not fetch config for ${name} (${res.status}) — leaving local files alone`);
     return exists;
   }
-  const c = res.json.data;
-
-  fs.mkdirSync(agentDir, { recursive: true });
-  if (typeof c.promptMd === 'string' && c.promptMd) {
-    fs.writeFileSync(path.join(agentDir, 'prompt.md'), c.promptMd);
-  }
-  if (typeof c.toolsYaml === 'string' && c.toolsYaml) {
-    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`);
-    }
+  const { models } = writePublishedAgentConfig(name, { ...res.json.data, version: configVersion });
+  for (const { slug, result } of models) {
+    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.
-  let existingCfg = {};
-  try { existingCfg = readAgentConfig(name) || {}; } catch { /* first sync */ }
-  const cfg = {
-    ...existingCfg,
-    name,
-    display_name: c.displayName || existingCfg.display_name || name,
-    description: c.description ?? existingCfg.description ?? '',
-    man: {
-      ...(existingCfg.man || {}),
-      agent_id: c.agentId,
-      ...(c.villageAgentId ? { village_agent_id: c.villageAgentId } : {}),
-      handle: c.handle || name,
-    },
-    ...(c.schedule ? { schedule: c.schedule } : {}),
-    ...(c.brain ? { brain: c.brain } : {}),
-  };
-  writeAgentConfig(name, cfg);
-
-  // Keep an empty .env so the daemon's loader and 0600 expectations hold, but
-  // never overwrite secrets a person put here.
-  const envPath = path.join(agentDir, '.env');
-  if (!fs.existsSync(envPath)) fs.writeFileSync(envPath, '', { mode: 0o600 });
-
-  fs.writeFileSync(syncedVersionPath(agentDir), String(configVersion));
   log(`synced ${name} config v${configVersion}${exists ? '' : ' (new on this machine)'}`);
   return true;
 }

package/src/commands/agent-local.js

@@ -15,6 +15,7 @@ import {
   listCommunities,
   getAgentActivity,
   listMyAgents,
+  getAgentPublishedConfig,
   listMyUnlinkedAgentProfiles,
   createVillageAgent as apiCreateVillageAgent,
   listAgentTasks,
@@ -45,6 +46,7 @@ import {
   readAgentLogs,
   getLogFilePath,
 } from '../utils/local-agent.js';
+import { writePublishedAgentConfig } from '../utils/agent-config-sync.js';
 import { scaffoldAgent, TOOL_CATALOG, resolveCatalogEntry } from '../utils/agent-scaffolder.js';
 import { loadAgentRecipe, listAgentRecipes } from '../utils/agent-recipes.js';
 import { formatLocalAgentList, formatLocalAgentStatus } from '../utils/formatters.js';
@@ -1315,12 +1317,12 @@ export async function agentRememberCommand(name, text, options = {}) {
 // already has the agent — this command scaffolds the missing local config
 // (~/.myvillage/agents/<handle>/) so `agent start` can launch the daemon.
 //
-// What pulls down: the network identity (id, handle, displayName) and a
-// link to the existing VillageAgent task queue.
-// What doesn't: custom prompt edits, tools.yaml customizations, and any
-// API keys. Those stay machine-local and you'll need to redo them if you
-// want an exact replica. The scaffold defaults are a reasonable starting
-// point that will boot.
+// What pulls down: the network identity (id, handle, displayName), a link to
+// the existing VillageAgent task queue, and — when the agent has a published
+// definition (Studio publishes on every save) — its prompt.md, tools.yaml,
+// schedule, model settings and trained models.
+// What doesn't: API keys and other .env secrets. Those stay machine-local.
+// An agent that was never published falls back to the scaffold defaults.
 
 async function fetchMyAgentByHandle(handle) {
   const result = await listMyAgents({ includeVillageAgent: true });
@@ -1365,8 +1367,17 @@ export async function agentPullCommand(handle, options = {}) {
     return;
   }
 
-  // Default scaffold: just the always-on MyVillage MCP tool. Users can add
-  // more via `agent add-tool` once they're up.
+  // The published definition, if there is one. A failure here is not fatal:
+  // the scaffold defaults still boot.
+  let published = null;
+  try {
+    const c = await getAgentPublishedConfig(profile.id);
+    if (c && c.version > 0) published = c;
+  } catch { /* fall back to defaults */ }
+
+  // Scaffold first so the directory has everything `start` expects (routines/,
+  // logs/, .env); the published definition is then written over the defaults.
+  // Default scaffold: just the always-on MyVillage MCP tool.
   const agentDir = getAgentDir(agentName);
   try {
     scaffoldAgent(agentDir, {
@@ -1394,6 +1405,16 @@ export async function agentPullCommand(handle, options = {}) {
   }
   writeAgentConfig(agentName, cfg);
 
+  let models = [];
+  if (published) {
+    try {
+      ({ models } = writePublishedAgentConfig(agentName, published));
+    } catch (err) {
+      spinner.warn(`Pulled ${handle}, but its saved setup couldn't be written: ${err.message}`);
+      published = null;
+    }
+  }
+
   spinner.succeed(`Pulled ${handle} to ~/.myvillage/agents/${agentName}/`);
 
   console.log('');
@@ -1404,11 +1425,25 @@ export async function agentPullCommand(handle, options = {}) {
   } else {
     console.log(`    - ${chalk.yellow('No VillageAgent shim found — one will be created on first start.')}`);
   }
-  console.log('');
-  console.log(brand.teal('  Defaults that may need tweaking:'));
-  console.log(`    - ${brand.gold('prompt.md')} (system prompt — generic template)`);
-  console.log(`    - ${brand.gold('tools.yaml')} (only the MyVillage tool is enabled)`);
-  console.log(`    - ${brand.gold('agent.config.yaml')} (anthropic + claude-sonnet by default)`);
+  if (published) {
+    const brain = published.brain;
+    console.log(`    - Saved setup v${published.version}: ${published.promptMd ? 'prompt.md, ' : ''}${published.toolsYaml ? 'tools.yaml, ' : ''}schedule & model settings`);
+    if (brain?.model) console.log(`    - Model: ${brain.provider ? `${brain.provider} / ` : ''}${brain.model}`);
+    const written = models.filter(m => m.result === 'written' || m.result === 'kept-local').map(m => m.slug);
+    if (written.length) console.log(`    - Trained models: ${written.join(', ')}`);
+    const skipped = models.filter(m => m.result === 'invalid').map(m => m.slug);
+    if (skipped.length) console.log(`    - ${chalk.yellow(`Skipped models whose files didn't check out: ${skipped.join(', ')}`)}`);
+    console.log('');
+    console.log(brand.teal('  Not included:'));
+    console.log(`    - ${brand.gold('.env')} secrets (API keys etc.) stay on the machine they were set on.`);
+  } else {
+    console.log('');
+    console.log(brand.teal('  No saved setup on the network yet, so these are defaults:'));
+    console.log(`    - ${brand.gold('prompt.md')} (system prompt — generic template)`);
+    console.log(`    - ${brand.gold('tools.yaml')} (only the MyVillage tool is enabled)`);
+    console.log(`    - ${brand.gold('agent.config.yaml')} (anthropic + claude-sonnet by default)`);
+    console.log(`    Open the agent in Studio and save once on the original machine to publish it.`);
+  }
   console.log('');
   console.log(brand.teal('  Next:'));
   console.log(`    ${brand.gold(`myvillage agent edit ${agentName}`)}    Customize prompt / tools`);

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-config-sync.js

@@ -0,0 +1,79 @@
+// Write an agent's published definition (GET /agents/:id/config) to its local
+// directory. Shared by the fleet runner, which keeps assigned agents in sync,
+// and `agent pull`, which rehydrates an agent on a new machine.
+//
+// `.env` is never written from the server: secrets stay per-machine until they
+// can be envelope-encrypted (see AgentConfig in the ed-platform schema).
+
+import fs from 'fs';
+import path from 'path';
+import { readAgentConfig, getAgentDir, writeAgentConfig } from './local-agent.js';
+import { writeSyncedModel } from './agent-models.js';
+
+// Records which published config version this machine last wrote, so the
+// runner only re-writes files when the definition actually changed.
+export function syncedVersionPath(agentDir) {
+  return path.join(agentDir, '.config-version');
+}
+
+export function readSyncedVersion(agentDir) {
+  try {
+    return Number(fs.readFileSync(syncedVersionPath(agentDir), 'utf8').trim()) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Materialise a published config `c` into ~/.myvillage/agents/<name>/.
+ * Anything already set locally that the control plane does not own is kept.
+ * Returns { models: [{ slug, result }] } so callers can report what happened.
+ */
+export function writePublishedAgentConfig(name, c) {
+  const agentDir = getAgentDir(name);
+  fs.mkdirSync(agentDir, { recursive: true });
+
+  if (typeof c.promptMd === 'string' && c.promptMd) {
+    fs.writeFileSync(path.join(agentDir, 'prompt.md'), c.promptMd);
+  }
+  if (typeof c.toolsYaml === 'string' && c.toolsYaml) {
+    fs.writeFileSync(path.join(agentDir, 'tools.yaml'), c.toolsYaml);
+  }
+
+  // The trained models this agent was given travel with its config.
+  const models = [];
+  if (c.models && typeof c.models === 'object') {
+    for (const [slug, entry] of Object.entries(c.models)) {
+      models.push({ slug, result: writeSyncedModel(slug, entry) });
+    }
+  }
+
+  // Compose agent.config.yaml from server-known identity + published schedule
+  // and brain, preserving anything already set locally that the control plane
+  // does not own.
+  let existingCfg = {};
+  try { existingCfg = readAgentConfig(name) || {}; } catch { /* first sync */ }
+  const cfg = {
+    ...existingCfg,
+    name,
+    display_name: c.displayName || existingCfg.display_name || name,
+    description: c.description ?? existingCfg.description ?? '',
+    man: {
+      ...(existingCfg.man || {}),
+      agent_id: c.agentId,
+      ...(c.villageAgentId ? { village_agent_id: c.villageAgentId } : {}),
+      handle: c.handle || name,
+    },
+    ...(c.schedule ? { schedule: c.schedule } : {}),
+    ...(c.brain ? { brain: c.brain } : {}),
+  };
+  writeAgentConfig(name, cfg);
+
+  // Keep an empty .env so the daemon's loader and 0600 expectations hold, but
+  // never overwrite secrets a person put here.
+  const envPath = path.join(agentDir, '.env');
+  if (!fs.existsSync(envPath)) fs.writeFileSync(envPath, '', { mode: 0o600 });
+
+  if (c.version) fs.writeFileSync(syncedVersionPath(agentDir), String(c.version));
+  return { models };
+}

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,
     },
 

package/src/utils/api.js

@@ -302,6 +302,14 @@ export async function listMyAgents(options = {}) {
   return response.data;
 }
 
+// The agent's published definition (prompt, tools, schedule, model settings,
+// trained models). Studio republishes it on every save.
+export async function getAgentPublishedConfig(id) {
+  const client = getNetworkClient();
+  const response = await client.get(`/agents/${id}/config`);
+  return response.data?.data ?? response.data;
+}
+
 export async function getAgent(id) {
   const client = getNetworkClient();
   const response = await client.get(`/agents/${id}`);