@myvillage/cli 1.26.0 → 1.30.0

package/package.json

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

package/src/agent-runtime/loop.js

@@ -2,7 +2,7 @@
 // Core agent loop using Vercel AI SDK. Reads prompt.md,
 // gathers context, calls LLM with tools, logs results.
 
-import { generateText } from 'ai';
+import { generateText, stepCountIs } from 'ai';
 import { createAnthropic } from '@ai-sdk/anthropic';
 import { createOpenAI } from '@ai-sdk/openai';
 import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync } from 'fs';
@@ -176,7 +176,15 @@ export async function agentLoop(agentName, { signal }) {
         const instructionText = activeTask.instruction
           || (activeTask.input ? JSON.stringify(activeTask.input, null, 2) : '');
 
-        systemPrompt = `${systemPrompt}\n\n## ACTIVE TASK MODE\nA client has assigned you a task. Your job this iteration is to execute the instruction below using your available tools. The feed context is provided only for situational awareness — do not let "no new feed activity" prevent you from carrying out the task.`;
+        systemPrompt = `${systemPrompt}\n\n## ACTIVE TASK MODE
+A client has assigned you the task below. Your job this iteration is to **execute it fully** using your available tools, not just acknowledge it.
+
+Guidelines:
+- Use as many tool calls as needed to complete the task. A single discovery call (e.g. listing directories) is usually NOT enough — follow up with the calls that actually produce the requested result.
+- Do not stop after one tool call unless that call alone fulfills the entire instruction.
+- Do not ask clarifying questions back to the user; make a reasonable interpretation and proceed.
+- The feed context is provided only for situational awareness — do not let "no new feed activity" prevent you from carrying out the task.
+- Your final text response should include the actual answer/output the user asked for (e.g. the list of files, the summary, the result), not just a description of what you did.`;
 
         context = `## TASK (id=${activeTask.id}, type=${activeTask.taskType})\n${instructionText}\n\n---\n\n## FEED CONTEXT (for awareness only)\n${context}`;
 
@@ -193,13 +201,20 @@ export async function agentLoop(agentName, { signal }) {
       });
 
       // 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 10 steps so a task like
+      // "find any README under the workspace" can do
+      // list_allowed_directories → list_directory → search_files → ...
+      // until it's actually done.
       const result = await generateText({
         model,
         system: systemPrompt,
         prompt: context,
         tools,
-        maxSteps: 5,
-        maxTokens,
+        stopWhen: stepCountIs(10),
+        maxOutputTokens: maxTokens,
       });
 
       // Log LLM response
@@ -215,6 +230,10 @@ export async function agentLoop(agentName, { signal }) {
 
       // 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) {
@@ -228,25 +247,39 @@ export async function agentLoop(agentName, { signal }) {
           if (step.toolCalls?.length && step.toolResults?.length) {
             for (let i = 0; i < step.toolResults.length; i++) {
               const tr = step.toolResults[i];
-              const args = step.toolCalls[i]?.args;
+              // 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: summarizeToolResult(tr),
+                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: summarizeToolResult(tr),
+                result: resultSummary,
                 ok: !errored,
               });
             }
@@ -259,10 +292,16 @@ export async function agentLoop(agentName, { signal }) {
           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: tc.args,
+            args,
             result: 'executed',
           });
         }
@@ -281,12 +320,12 @@ export async function agentLoop(agentName, { signal }) {
       if (result.steps?.length) {
         for (const step of result.steps) {
           for (const tc of step.toolCalls || []) {
-            collectActions(tc.toolName, tc.args);
+            collectActions(tc.toolName, tc.input ?? tc.args);
           }
         }
       } else if (result.toolCalls?.length) {
         for (const tc of result.toolCalls) {
-          collectActions(tc.toolName, tc.args);
+          collectActions(tc.toolName, tc.input ?? tc.args);
         }
       }
       // Keep only last 50 actions to bound memory
@@ -310,7 +349,8 @@ export async function agentLoop(agentName, { signal }) {
               errorMessage,
               output: {
                 text: result.text || '',
-                toolCalls: activity.toolCalls,
+                toolCallCount: activity.toolCalls,
+                toolCalls: toolCallSummary,
                 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.',
               },
@@ -326,7 +366,8 @@ export async function agentLoop(agentName, { signal }) {
             await completeAgentTask(config.man.village_agent_id, activeTask.id, {
               output: {
                 text: result.text || '',
-                toolCalls: activity.toolCalls,
+                toolCallCount: activity.toolCalls,
+                toolCalls: toolCallSummary,
                 toolErrors: taskActionAudit.toolErrors.length > 0 ? taskActionAudit.toolErrors : undefined,
               },
               tokensUsed: result.usage?.totalTokens || 0,
@@ -452,7 +493,10 @@ const ACTION_TOOLS = new Set([
 
 function flattenToolResultText(tr) {
   if (!tr) return '';
-  const r = tr.result;
+  // AI SDK v6 renamed `result` → `output`. Fall back to the old name so
+  // older SDK versions still work if anyone pins them.
+  const r = tr.output ?? tr.result;
+  if (r == null) return '';
   if (typeof r === 'string') return r;
   if (Array.isArray(r?.content)) {
     return r.content

package/src/agent-runtime/mcp-client.js

@@ -102,15 +102,23 @@ export async function getMCPTools(agentDir, agentConfig) {
           },
         }), `${name} (${transport} ${server.url})`);
       } else {
-        // Local MCP servers via stdio transport
-        client = await withTimeout(createMCPClient({
-          transport: {
-            type: 'stdio',
-            command: server.command,
-            args: server.args || [],
-            env: { ...process.env, ...resolveEnvVars(server.env || {}) },
-          },
-        }), `${name} (stdio ${server.command})`);
+        // Local MCP servers via stdio transport.
+        //
+        // @ai-sdk/mcp v1 doesn't accept a `{ type: 'stdio', ... }` config —
+        // its MCPTransportConfig is HTTP-only (`'sse' | 'http'`). For stdio
+        // you must instantiate the transport class explicitly from the
+        // `/mcp-stdio` subpath and pass the instance.
+        const { Experimental_StdioMCPTransport } =
+          await import('@ai-sdk/mcp/mcp-stdio');
+        const stdioTransport = new Experimental_StdioMCPTransport({
+          command: server.command,
+          args: server.args || [],
+          env: { ...process.env, ...resolveEnvVars(server.env || {}) },
+        });
+        client = await withTimeout(
+          createMCPClient({ transport: stdioTransport }),
+          `${name} (stdio ${server.command})`,
+        );
       }
 
       activeClients.push(client);

package/src/commands/agent-local.js

@@ -4,6 +4,7 @@ import { villageSpinner, brand } from '../utils/brand.js';
 import inquirer from 'inquirer';
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
+import { homedir } from 'os';
 import { execSync } from 'child_process';
 import { isAuthenticated, getAccessToken } from '../utils/auth.js';
 import { getConfig, setConfig } from '../utils/config.js';
@@ -12,6 +13,7 @@ import {
   agentJoinCommunity as apiAgentJoinCommunity,
   listCommunities,
   getAgentActivity,
+  listMyAgents,
   listMyUnlinkedAgentProfiles,
   createVillageAgent as apiCreateVillageAgent,
   listAgentTasks,
@@ -41,7 +43,7 @@ import {
   readAgentLogs,
   getLogFilePath,
 } from '../utils/local-agent.js';
-import { scaffoldAgent, TOOL_CATALOG } from '../utils/agent-scaffolder.js';
+import { scaffoldAgent, TOOL_CATALOG, resolveCatalogEntry } from '../utils/agent-scaffolder.js';
 import { formatLocalAgentList, formatLocalAgentStatus } from '../utils/formatters.js';
 
 // ── Create Local Agent (wizard) ─────────────────────────
@@ -117,11 +119,11 @@ export async function agentCreateLocalCommand() {
         message: 'Which tools should your agent have?',
         choices: [
           { name: 'MyVillageOS MCP (feed, posts, communities, wallet)', value: 'myvillage', checked: true, disabled: 'always enabled' },
-          { name: 'Local Files (read/write project files)', value: 'filesystem', checked: true },
+          { name: 'Local Files (read/write a sandboxed workspace)', value: 'filesystem', checked: true },
           { name: 'Gmail', value: 'gmail' },
           { name: 'Calendar', value: 'calendar' },
           { name: 'GitHub', value: 'github' },
-          { name: 'Browser', value: 'browser' },
+          { name: 'Browser (Puppeteer — downloads Chromium on first run)', value: 'browser' },
         ],
       },
       {
@@ -230,6 +232,26 @@ export async function agentStartCommand(name) {
   }
 
   if (!agentExists(name)) {
+    // Check whether the agent exists server-side under this handle. If so,
+    // this is a "different machine" situation \u2014 point them at `agent pull`
+    // rather than the misleading "not found" dead-end.
+    let remoteMatch = null;
+    try {
+      remoteMatch = await fetchMyAgentByHandle(name);
+    } catch {
+      // network error \u2014 fall through to the generic message below
+    }
+
+    if (remoteMatch) {
+      console.log(chalk.yellow(
+        `  Agent "${name}" exists on the server but isn't set up on this machine yet.`,
+      ));
+      console.log(chalk.yellow(
+        `  Run ${brand.gold(`myvillage agent pull ${name}`)} to scaffold it locally, then start it.\n`,
+      ));
+      return;
+    }
+
     console.log(chalk.red(`  \u2717 Agent "${name}" not found. Run 'myvillage agent' to see your agents.\n`));
     return;
   }
@@ -396,7 +418,7 @@ export async function agentStartCommand(name) {
   const toolsConfig = readToolsYaml(name);
   if (toolsConfig.servers?.['man-feed'] && !toolsConfig.servers?.['myvillage']) {
     delete toolsConfig.servers['man-feed'];
-    toolsConfig.servers = { myvillage: TOOL_CATALOG['myvillage'], ...toolsConfig.servers };
+    toolsConfig.servers = { myvillage: resolveCatalogEntry('myvillage', name), ...toolsConfig.servers };
     writeToolsYaml(name, toolsConfig);
   }
 
@@ -648,9 +670,22 @@ function printLogEntry(entry) {
         console.log(`  ${' '.repeat(10)}  ${brand.teal(`Tokens: ${entry.tokensUsed.prompt || 0}p / ${entry.tokensUsed.completion || 0}c`)}`);
       }
       break;
-    case 'tool_call':
-      console.log(`  ${time}  ${chalk.yellow('TOOL')}   ${entry.tool || '?'} ${brand.teal(`→ ${entry.result || 'ok'}`)}`);
+    case 'tool_call': {
+      const arrow = entry.ok === false ? chalk.red('→') : brand.teal('→');
+      const statusLabel = entry.ok === false ? chalk.red('error') : '';
+      console.log(`  ${time}  ${chalk.yellow('TOOL')}   ${entry.tool || '?'} ${arrow} ${statusLabel}`);
+      // Show args (if any) and the result content on indented sub-lines,
+      // so a developer tailing logs can actually see what the agent did.
+      if (entry.args && Object.keys(entry.args).length > 0) {
+        const argsStr = truncateLog(JSON.stringify(entry.args), 200);
+        console.log(`  ${' '.repeat(10)}  ${brand.teal('args:')} ${argsStr}`);
+      }
+      if (entry.result && entry.result !== 'ok' && entry.result !== 'executed') {
+        const resultStr = truncateLog(String(entry.result), 200);
+        console.log(`  ${' '.repeat(10)}  ${brand.teal('result:')} ${resultStr}`);
+      }
       break;
+    }
     case 'error':
       console.log(`  ${time}  ${chalk.red('ERR')}    ${entry.error || entry.message || 'Unknown error'}`);
       break;
@@ -710,11 +745,15 @@ export async function agentAddToolCommand(name, tool) {
   }
 
   toolsConfig.servers = toolsConfig.servers || {};
-  toolsConfig.servers[tool] = { ...TOOL_CATALOG[tool] };
+  toolsConfig.servers[tool] = resolveCatalogEntry(tool, name);
   writeToolsYaml(name, toolsConfig);
 
   console.log(brand.green(`  \u2713 Added "${tool}" to agent "${name}".`));
 
+  if (tool === 'filesystem') {
+    const workspace = join(homedir(), '.myvillage', 'agents', name, 'workspace');
+    console.log(brand.teal(`  Workspace: ${workspace}`));
+  }
   if (tool === 'github') {
     console.log(brand.teal('  Note: Set GITHUB_TOKEN in your environment for GitHub access.'));
   }
@@ -1091,3 +1130,111 @@ export async function agentRememberCommand(name, text, options = {}) {
     console.log(chalk.red(`  ✗ Remember failed: ${msg}\n`));
   }
 }
+
+// ── Pull Agent ─────────────────────────────────────────
+//
+// Rehydrate a local agent directory on a new machine from the server's
+// AgentProfile + VillageAgent records. Use case: you created `teacher_mvp`
+// on your laptop, now you want to run it on your desktop. The server
+// 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.
+
+async function fetchMyAgentByHandle(handle) {
+  const result = await listMyAgents({ includeVillageAgent: true });
+  const agents = result.data || result;
+  if (!Array.isArray(agents)) return null;
+  return agents.find(a => a.handle === handle) || null;
+}
+
+export async function agentPullCommand(handle, options = {}) {
+  if (!isAuthenticated()) {
+    console.log(chalk.red('  ✗ Authentication required. Run \'myvillage login\' first.'));
+    return;
+  }
+
+  // The local agent dir is keyed off the handle (= server-side AgentProfile.handle).
+  const agentName = handle;
+  const force = options.force === true;
+
+  if (agentExists(agentName) && !force) {
+    console.log(chalk.yellow(
+      `  Agent "${agentName}" already exists locally at ~/.myvillage/agents/${agentName}/`,
+    ));
+    console.log(chalk.yellow('  Use --force to overwrite, or just `myvillage agent start ' + agentName + '` to run it.\n'));
+    return;
+  }
+
+  const spinner = villageSpinner(`Pulling ${handle} from the network...`).start();
+
+  let profile;
+  try {
+    profile = await fetchMyAgentByHandle(handle);
+  } catch (err) {
+    spinner.fail(`Failed to look up agent: ${err.response?.data?.error || err.message}`);
+    return;
+  }
+
+  if (!profile) {
+    spinner.fail(`No agent with handle "${handle}" is owned by your account.`);
+    console.log(chalk.yellow(
+      '  Run `myvillage agent` to see the agents on your account, then pull one by its handle.\n',
+    ));
+    return;
+  }
+
+  // Default scaffold: just the always-on MyVillage MCP tool. Users can add
+  // more via `agent add-tool` once they're up.
+  const agentDir = getAgentDir(agentName);
+  try {
+    scaffoldAgent(agentDir, {
+      name: agentName,
+      displayName: profile.displayName || agentName,
+      description: profile.bio || `Pulled from the network on ${new Date().toISOString().split('T')[0]}.`,
+      tools: ['myvillage'],
+      checkInInterval: 'hourly',
+      provider: 'anthropic',
+      model: 'claude-sonnet-4-5-20250929',
+    });
+  } catch (err) {
+    spinner.fail(`Failed to scaffold local agent: ${err.message}`);
+    return;
+  }
+
+  // Prefill man.agent_id and man.village_agent_id so `start` skips the
+  // create-on-first-boot step and links straight to the existing server rows.
+  const cfg = readAgentConfig(agentName);
+  cfg.man = cfg.man || {};
+  cfg.man.agent_id = profile.id;
+  cfg.man.handle = profile.handle;
+  if (profile.villageAgent?.id) {
+    cfg.man.village_agent_id = profile.villageAgent.id;
+  }
+  writeAgentConfig(agentName, cfg);
+
+  spinner.succeed(`Pulled ${handle} to ~/.myvillage/agents/${agentName}/`);
+
+  console.log('');
+  console.log(brand.teal('  What pulled down:'));
+  console.log(`    - Network identity: @${profile.handle} (${profile.displayName})`);
+  if (profile.villageAgent?.id) {
+    console.log(`    - VillageAgent task queue: ${profile.villageAgent.id}`);
+  } 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)`);
+  console.log('');
+  console.log(brand.teal('  Next:'));
+  console.log(`    ${brand.gold(`myvillage agent edit ${agentName}`)}    Customize prompt / tools`);
+  console.log(`    ${brand.gold(`myvillage agent start ${agentName}`)}   Launch the daemon\n`);
+}

package/src/index.js

@@ -55,6 +55,7 @@ import {
   agentStopCommand,
   agentStatusCommand,
   agentLogsCommand,
+  agentPullCommand,
   agentAddToolCommand,
   agentRemoveToolCommand,
   agentTaskListCommand,
@@ -78,13 +79,6 @@ import {
   agentDeactivateClientCommand,
   agentRotateClientKeyCommand,
 } from './commands/agent-client.js';
-import {
-  bizreqsNewCommand,
-  bizreqsSpecCommand,
-  bizreqsListCommand,
-  bizreqsStatusCommand,
-  bizreqsImportCommand,
-} from './commands/bizreqs.js';
 import {
   gameUpdateCommand,
   gameUploadThumbnailCommand,
@@ -447,6 +441,12 @@ export function run() {
     .description('Start a local agent daemon')
     .action(agentStartCommand);
 
+  agentCmd
+    .command('pull <handle>')
+    .description('Rehydrate a local agent dir on a new machine from the server')
+    .option('--force', 'Overwrite an existing local agent dir')
+    .action(agentPullCommand);
+
   agentCmd
     .command('stop <name>')
     .description('Stop a local agent daemon')
@@ -645,55 +645,6 @@ export function run() {
     .description('Show status of a reel draft')
     .action(mediaDraftStatusCommand);
 
-  // ── BizReqs: Business Requirements Pipeline ───────────
-
-  const bizreqsCmd = program
-    .command('bizreqs')
-    .description('Business requirements intake and project pipeline');
-
-  bizreqsCmd
-    .command('new')
-    .description('Start a new AI-guided business intake session')
-    .option('--org <name>', 'Organization name')
-    .option('--contact <name>', 'Contact name')
-    .option('--from-file <path>', 'Path to a text file with initial context')
-    .option('--from-url <url>', 'URL to the organization\'s website')
-    .option('--quick', 'Shortened flow (skip dream state, fewer exchanges)')
-    .action(bizreqsNewCommand);
-
-  bizreqsCmd
-    .command('spec <id>')
-    .description('Generate full project specification from an intake')
-    .option('--detail <level>', 'Detail level: brief, standard, comprehensive', 'standard')
-    .option('--output <dir>', 'Output directory for spec file', './specs')
-    .action(bizreqsSpecCommand);
-
-  bizreqsCmd
-    .command('list')
-    .description('List pipeline submissions')
-    .option('--status <status>', 'Filter: new, in-review, spec-ready, assigned, in-progress, delivered')
-    .option('--city <city>', 'Filter by city')
-    .option('--search <query>', 'Search by org name, solution, or ID')
-    .option('--sort <sort>', 'Sort: newest, oldest, priority', 'newest')
-    .option('-n, --limit <number>', 'Number of results', '50')
-    .option('--offset <number>', 'Pagination offset', '0')
-    .option('--json', 'Output raw JSON')
-    .action(bizreqsListCommand);
-
-  bizreqsCmd
-    .command('status <id>')
-    .description('Check project status')
-    .action(bizreqsStatusCommand);
-
-  bizreqsCmd
-    .command('import')
-    .description('Import requirements from a file or URL')
-    .option('--file <path>', 'Path to .txt or .md file')
-    .option('--url <url>', 'URL to fetch content from')
-    .option('--org <name>', 'Organization name')
-    .option('--contact <name>', 'Contact name')
-    .action(bizreqsImportCommand);
-
   // ── SoulPrint Studio: Model Training Pipeline ───────────
 
   // \u2500\u2500 Wisdom: agent skill packs (Books of Wisdom) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500

package/src/utils/agent-scaffolder.js

@@ -1,8 +1,13 @@
-import { mkdirSync, writeFileSync } from 'fs';
+import { mkdirSync, writeFileSync, existsSync } from 'fs';
 import { join } from 'path';
+import { homedir } from 'os';
 import { stringify as stringifyYaml } from 'yaml';
 
 // ── MCP Tool Catalog ────────────────────────────────────
+//
+// Static-shape entries. The `filesystem` entry's allow-listed root is
+// resolved per-agent at scaffold/add-tool time — see
+// resolveCatalogEntry() — so each agent gets its own sandboxed workspace.
 
 const TOOL_CATALOG = {
   myvillage: {
@@ -12,8 +17,10 @@ const TOOL_CATALOG = {
   },
   filesystem: {
     command: 'npx',
-    args: ['-y', '@modelcontextprotocol/server-filesystem', '~/projects'],
-    description: 'Read/write local project files',
+    // Last arg is a placeholder; replaced with `<agentDir>/workspace`
+    // by resolveCatalogEntry().
+    args: ['-y', '@modelcontextprotocol/server-filesystem', '__AGENT_WORKSPACE__'],
+    description: 'Read/write files under the agent\'s sandboxed workspace',
   },
   gmail: {
     command: 'npx',
@@ -33,13 +40,41 @@ const TOOL_CATALOG = {
   },
   browser: {
     command: 'npx',
-    args: ['-y', '@anthropic/mcp-puppeteer'],
-    description: 'Navigate web pages, extract content',
+    args: ['-y', '@modelcontextprotocol/server-puppeteer'],
+    description: 'Navigate web pages, extract content (downloads Chromium on first run)',
   },
 };
 
 export { TOOL_CATALOG };
 
+// ── Catalog Resolution ──────────────────────────────────
+
+/**
+ * Returns a deep-copied catalog entry with per-agent placeholders
+ * resolved (e.g. the filesystem workspace path). Also creates any
+ * directories the entry depends on (the workspace dir for filesystem).
+ *
+ * Use this anywhere you'd otherwise do `{ ...TOOL_CATALOG[toolId] }`
+ * to write into a tools.yaml.
+ */
+export function resolveCatalogEntry(toolId, agentName) {
+  const entry = TOOL_CATALOG[toolId];
+  if (!entry) return null;
+  const resolved = JSON.parse(JSON.stringify(entry));
+
+  if (toolId === 'filesystem') {
+    const workspace = join(homedir(), '.myvillage', 'agents', agentName, 'workspace');
+    if (!existsSync(workspace)) {
+      mkdirSync(workspace, { recursive: true });
+    }
+    resolved.args = resolved.args.map(a =>
+      a === '__AGENT_WORKSPACE__' ? workspace : a,
+    );
+  }
+
+  return resolved;
+}
+
 // ── Check-in Interval Map ───────────────────────────────
 
 const INTERVAL_MAP = {
@@ -73,7 +108,7 @@ export function scaffoldAgent(agentDir, options) {
   // Write tools.yaml
   writeFileSync(
     join(agentDir, 'tools.yaml'),
-    generateToolsYaml(tools)
+    generateToolsYaml(tools, name)
   );
 
   // Write logs/.gitkeep
@@ -156,17 +191,16 @@ When you receive a TASK in your context, follow these rules:
 
 // ── Tools YAML Generation ───────────────────────────────
 
-function generateToolsYaml(selectedTools) {
+function generateToolsYaml(selectedTools, agentName) {
   const servers = {};
 
   // myvillage is always included
-  servers['myvillage'] = TOOL_CATALOG['myvillage'];
+  servers['myvillage'] = resolveCatalogEntry('myvillage', agentName);
 
   for (const toolId of selectedTools) {
     if (toolId === 'myvillage') continue;
-    if (TOOL_CATALOG[toolId]) {
-      servers[toolId] = { ...TOOL_CATALOG[toolId] };
-    }
+    const entry = resolveCatalogEntry(toolId, agentName);
+    if (entry) servers[toolId] = entry;
   }
 
   return stringifyYaml({ servers }, { lineWidth: 0 });