@myvillage/cli 1.23.3 → 1.28.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myvillage/cli",
-  "version": "1.23.3",
+  "version": "1.28.1",
   "description": "MyVillageOS CLI for community developers",
   "type": "module",
   "bin": {
@@ -26,7 +26,7 @@
   "author": "MyVillage Project",
   "license": "MIT",
   "dependencies": {
-    "@ai-sdk/anthropic": "^1.0.0",
+    "@ai-sdk/anthropic": "^3.0.78",
     "@ai-sdk/mcp": "^1.0.42",
     "@ai-sdk/openai": "^3.0.33",
     "ai": "^6.0.0",

package/src/agent-runtime/daemon-entry.js

@@ -4,6 +4,19 @@
 // It receives the agent name as a command-line argument,
 // writes a PID file, runs the agent loop, and cleans up.
 
+// Surface silent killers (uncaught exceptions, unhandled rejections, and
+// event-loop-emptied exits) to the captured stderr file so a failed start
+// always leaves a diagnostic trail.
+process.on('uncaughtException', (err) => {
+  process.stderr.write(`[daemon-entry] UNCAUGHT EXCEPTION: ${err?.stack || err}\n`);
+});
+process.on('unhandledRejection', (reason) => {
+  process.stderr.write(`[daemon-entry] UNHANDLED REJECTION: ${reason?.stack || reason}\n`);
+});
+process.on('beforeExit', (code) => {
+  process.stderr.write(`[daemon-entry] BEFORE EXIT code=${code} — event loop emptied (likely a hung await inside agent setup)\n`);
+});
+
 import { writeFileSync, unlinkSync, existsSync, mkdirSync, appendFileSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';

package/src/agent-runtime/daemon.js

@@ -5,16 +5,35 @@
 import { fork } from 'child_process';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { existsSync, readFileSync, unlinkSync } from 'fs';
+import { existsSync, readFileSync, unlinkSync, openSync, mkdirSync } from 'fs';
 import { homedir } from 'os';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+export function getDaemonStderrPath(agentName) {
+  return join(homedir(), '.myvillage', 'agents', agentName, 'logs', 'daemon-stderr.log');
+}
+
 export function startDaemon(agentName) {
   const entryScript = join(__dirname, 'daemon-entry.js');
+
+  // Capture daemon stderr to a file so crashes that happen BEFORE the loop
+  // starts logging (e.g. ESM module-resolution errors at top-level import)
+  // are visible. Without this, `stdio: 'ignore'` silently discarded the
+  // only signal of what went wrong, leaving the developer with a blank
+  // log file and no error.
+  const logsDir = join(homedir(), '.myvillage', 'agents', agentName, 'logs');
+  if (!existsSync(logsDir)) {
+    mkdirSync(logsDir, { recursive: true });
+  }
+  const stderrPath = getDaemonStderrPath(agentName);
+  // Open with 'w' to truncate so stale crashes from previous starts don't
+  // mislead the diagnostic.
+  const stderrFd = openSync(stderrPath, 'w');
+
   const child = fork(entryScript, [agentName], {
     detached: true,
-    stdio: 'ignore',
+    stdio: ['ignore', 'ignore', stderrFd, 'ipc'],
   });
   child.unref();
   return child.pid;

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
@@ -207,13 +222,18 @@ export async function agentLoop(agentName, { signal }) {
         type: 'llm_response',
         text: (result.text || '').slice(0, 500),
         tokensUsed: {
-          prompt: result.usage?.promptTokens || 0,
-          completion: result.usage?.completionTokens || 0,
+          prompt: result.usage?.inputTokens || 0,
+          completion: result.usage?.outputTokens || 0,
+          total: result.usage?.totalTokens || 0,
         },
       });
 
       // 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) {
@@ -227,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,
               });
             }
@@ -258,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',
           });
         }
@@ -280,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
@@ -309,11 +349,12 @@ 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.',
               },
-              tokensUsed: (result.usage?.promptTokens || 0) + (result.usage?.completionTokens || 0),
+              tokensUsed: result.usage?.totalTokens || 0,
               durationMs: Date.now() - loopStart,
             });
             logActivity(agentDir, {
@@ -325,10 +366,11 @@ 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?.promptTokens || 0) + (result.usage?.completionTokens || 0),
+              tokensUsed: result.usage?.totalTokens || 0,
               durationMs: Date.now() - loopStart,
             });
             logActivity(agentDir, { type: 'task_completed', taskId: activeTask.id });
@@ -347,7 +389,7 @@ export async function agentLoop(agentName, { signal }) {
             votesGiven: activity.votesGiven,
             toolCalls: activity.toolCalls,
             modelUsed: modelId,
-            tokensUsed: (result.usage?.promptTokens || 0) + (result.usage?.completionTokens || 0),
+            tokensUsed: result.usage?.totalTokens || 0,
             durationMs: Date.now() - loopStart,
             activitySummary: { feedItemsRead, mentionsFound },
           });
@@ -451,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

@@ -33,7 +33,10 @@ export async function getMCPTools(agentDir, agentConfig) {
       continue;
     }
 
-    const transport = server.url ? 'sse' : 'stdio';
+    // URL-based servers default to Streamable HTTP (the current MCP
+    // standard), but allow `transport: 'sse'` in tools.yaml for legacy
+    // SSE-only servers.
+    const transport = server.url ? (server.transport || 'http') : 'stdio';
 
     try {
       // AI SDK v6 moved the MCP client into a separate package
@@ -55,34 +58,67 @@ export async function getMCPTools(agentDir, agentConfig) {
           + `npm uninstall -g @myvillage/cli && npm install -g @myvillage/cli`
         );
       }
+      // Wrap createMCPClient with a hard timeout. Without this, @ai-sdk/mcp's
+      // SSE transport can return a never-settling promise when the endpoint
+      // doesn't respond as expected — and because nothing else keeps the
+      // event loop alive during agent startup, Node will exit cleanly with
+      // code 0, bypassing every try/catch and .finally we've set up.
+      const MCP_CONNECT_TIMEOUT_MS = 30000;
+      const withTimeout = (promise, label) => Promise.race([
+        promise,
+        new Promise((_, reject) => setTimeout(
+          () => reject(new Error(`MCP connect timed out after ${MCP_CONNECT_TIMEOUT_MS}ms (${label})`)),
+          MCP_CONNECT_TIMEOUT_MS,
+        )),
+      ]);
       let client;
 
       if (server.url) {
         // Remote MCP server via Streamable HTTP transport
         const headers = {};
-        if (process.env.MYVILLAGE_ACCESS_TOKEN) {
-          headers['Authorization'] = `Bearer ${process.env.MYVILLAGE_ACCESS_TOKEN}`;
-        }
-        if (process.env.MYVILLAGE_AGENT_ID) {
-          headers['X-Agent-Id'] = process.env.MYVILLAGE_AGENT_ID;
+
+        // Auto-attach the MyVillage bearer ONLY for MyVillage hostnames.
+        // Sending an in-session OAuth token to an arbitrary third-party
+        // MCP would be a credential leak.
+        if (isMyVillageHost(server.url)) {
+          if (process.env.MYVILLAGE_ACCESS_TOKEN) {
+            headers['Authorization'] = `Bearer ${process.env.MYVILLAGE_ACCESS_TOKEN}`;
+          }
+          if (process.env.MYVILLAGE_AGENT_ID) {
+            headers['X-Agent-Id'] = process.env.MYVILLAGE_AGENT_ID;
+          }
         }
-        client = await createMCPClient({
+
+        // Per-server headers from tools.yaml (with `${VAR}` env expansion).
+        // These win over the auto-attached MyVillage headers so a developer
+        // can override on the same host if they need to.
+        Object.assign(headers, resolveEnvVars(server.headers || {}));
+
+        client = await withTimeout(createMCPClient({
           transport: {
-            type: 'sse',
+            type: transport,
             url: server.url,
             headers,
           },
-        });
+        }), `${name} (${transport} ${server.url})`);
       } else {
-        // Local MCP servers via stdio transport
-        client = await createMCPClient({
-          transport: {
-            type: 'stdio',
-            command: server.command,
-            args: server.args || [],
-            env: { ...process.env, ...resolveEnvVars(server.env || {}) },
-          },
+        // 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);
@@ -121,6 +157,15 @@ export async function cleanupMCPClients() {
 
 // ── Helpers ─────────────────────────────────────────────
 
+function isMyVillageHost(urlString) {
+  try {
+    const host = new URL(urlString).hostname;
+    return host === 'myvillageproject.ai' || host.endsWith('.myvillageproject.ai');
+  } catch {
+    return false;
+  }
+}
+
 function resolveEnvVars(envMap) {
   const resolved = {};
   for (const [key, val] of Object.entries(envMap)) {

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';
@@ -41,7 +42,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 +118,10 @@ 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' },
         ],
       },
       {
@@ -396,7 +396,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);
   }
 
@@ -416,7 +416,7 @@ export async function agentStartCommand(name) {
   const spinner = villageSpinner(`Starting agent "${name}"...`).start();
 
   try {
-    const { startDaemon } = await import('../agent-runtime/daemon.js');
+    const { startDaemon, getDaemonStderrPath } = await import('../agent-runtime/daemon.js');
     startDaemon(name);
 
     // Wait briefly for PID file to appear
@@ -437,6 +437,25 @@ export async function agentStartCommand(name) {
       const lastError = [...recent].reverse().find(e => e.type === 'error');
       if (lastError?.error) {
         console.log(chalk.red(`  ${lastError.error}`));
+      } else {
+        // Daemon died before it could write a single log entry. Fall back
+        // to the stderr capture file — catches top-level ESM resolution
+        // errors, missing modules, syntax errors, etc.
+        const stderrPath = getDaemonStderrPath(name);
+        if (existsSync(stderrPath)) {
+          try {
+            const stderrText = readFileSync(stderrPath, 'utf-8').trim();
+            if (stderrText) {
+              console.log(chalk.red('  Daemon stderr:'));
+              // Indent each line for readability and cap output length so a
+              // multi-MB stack trace doesn't drown the terminal.
+              const trimmed = stderrText.length > 2000
+                ? stderrText.slice(0, 2000) + '\n... (truncated; see ' + stderrPath + ')'
+                : stderrText;
+              console.log(trimmed.split('\n').map(l => '    ' + l).join('\n'));
+            }
+          } catch { /* ignore */ }
+        }
       }
       console.log(brand.teal(`  Full logs: myvillage agent logs ${name}\n`));
     }
@@ -629,9 +648,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;
@@ -691,11 +723,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.'));
   }

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',
@@ -31,15 +38,41 @@ const TOOL_CATALOG = {
     env: { GITHUB_TOKEN: '${GITHUB_TOKEN}' },
     description: 'GitHub repository access',
   },
-  browser: {
-    command: 'npx',
-    args: ['-y', '@anthropic/mcp-puppeteer'],
-    description: 'Navigate web pages, extract content',
-  },
+  // browser: removed in v1.27.0 — the previously catalog'd
+  // `@anthropic/mcp-puppeteer` package is no longer published under that
+  // name. Add a working browser MCP back when one stabilizes.
 };
 
 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 +106,7 @@ export function scaffoldAgent(agentDir, options) {
   // Write tools.yaml
   writeFileSync(
     join(agentDir, 'tools.yaml'),
-    generateToolsYaml(tools)
+    generateToolsYaml(tools, name)
   );
 
   // Write logs/.gitkeep
@@ -156,17 +189,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 });