mixdog 1.1.2 → 1.2.1

package/src/runtime/agent/orchestrator/context/skill-catalog.mjs

@@ -3,15 +3,16 @@
 
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
-import { maxMtimeRecursive } from '../cache-mtime.mjs';
+import { maxMtimeRecursive, mtimeSignatureRecursive } from '../cache-mtime.mjs';
 import { mixdogHome, resolvePluginData, mixdogRoot } from '../../../shared/plugin-paths.mjs';
-import { pluginSkillsRoots } from '../../../shared/plugin-manifest.mjs';
+import { PLUGIN_MANIFEST_FILES, pluginSkillsRoots } from '../../../shared/plugin-manifest.mjs';
 import {
   parseSkillDocument,
   SKILL_TRIGGER_LISTING_MAX,
   SKILL_TRIGGER_LISTING_MIN,
 } from '../../../shared/skill-document.mjs';
 import { readSkillToolDependencies, skillToolDependenciesRoot } from '../../../shared/skill-tool-dependencies.mjs';
+import { SKILL_LAUNCHER_COMMAND } from '../../../shared/skill-script-runtime.mjs';
 import { loadConfig, normalizeSkillsConfig } from '../config.mjs';
 import { builtinFeatureActive, withGrandfatheredBuiltins } from '../runtime-core/builtin-features.mjs';
 import { SKILL_TOOL } from '../runtime-core/tool-defs.mjs';
@@ -88,6 +89,32 @@ function pluginSkillDirs() {
   return dirs;
 }
 
+/** Paths whose own mtime (no recursion) gates the skill list for enabled
+ *  registered plugins: every manifest file, plus the nearest existing ancestor
+ *  of each candidate skills root (so a skills dir created later is noticed). */
+function pluginShallowWatchPaths() {
+  const registryPath = pluginRegistryPath();
+  let registry;
+  try {
+    registry = JSON.parse(readFileSync(registryPath, 'utf-8'));
+  } catch {
+    return [];
+  }
+  const paths = [];
+  for (const entry of Array.isArray(registry?.plugins) ? registry.plugins : []) {
+    if (entry?.enabled === false) continue;
+    const root = entry && typeof entry.root === 'string' ? entry.root : null;
+    if (!root || !existsSync(root)) continue;
+    for (const rel of PLUGIN_MANIFEST_FILES) paths.push(join(root, ...rel.split('/')));
+    for (const skillsDir of pluginSkillsRoots(root)) {
+      let dir = skillsDir;
+      while (!existsSync(dir) && dirname(dir) !== dir) dir = dirname(dir);
+      paths.push(dir);
+    }
+  }
+  return paths;
+}
+
 export function readSafe(path) {
   try {
     if (!existsSync(path)) return null;
@@ -216,24 +243,39 @@ function followsBuiltinFeature(skill) {
   return skill?.source === 'builtin' && Array.isArray(skill.requires) && skill.requires.length > 0;
 }
 
-function findCachedSkillByKey(key) {
-  return collectSkillsCached(null).find((entry) => normalizeSkillNameKey(entry.name) === key);
+function findCachedSkillByKey(key, skills = null) {
+  return (skills || collectSkillsCached(null)).find((entry) => normalizeSkillNameKey(entry.name) === key);
 }
 
-export function isSkillDisabled(name, config = null) {
+/** `skills`: optional snapshot from one collectSkillsCached() call, reused so a
+ *  batch of per-skill checks scans the disk once. */
+export function isSkillDisabled(name, config = null, skills = null) {
   const n = normalizeSkillNameKey(name);
   if (!n) return false;
-  const skill = findCachedSkillByKey(n);
+  const skill = findCachedSkillByKey(n, skills);
   if (!followsBuiltinFeature(skill) && getDisabledSkillNameSet(config).has(n)) return true;
   return Boolean(skill && missingFeature(skill, featureConfig(config)));
 }
 
 /** The built-in feature a skill needs that is not active, or null. */
-export function skillMissingFeature(name, config = null) {
-  const skill = findCachedSkillByKey(normalizeSkillNameKey(name));
+export function skillMissingFeature(name, config = null, skills = null) {
+  const skill = findCachedSkillByKey(normalizeSkillNameKey(name), skills);
   return skill ? missingFeature(skill, featureConfig(config)) : null;
 }
 
+/** True when an installed skill exists but its (or its plugin's) project scope
+ *  excludes `cwd` — the same scope rule filterSkillsExcludingDisabled applies. */
+export function skillOutsideScope(name, cwd, config = null, skills = null) {
+  const skill = findCachedSkillByKey(normalizeSkillNameKey(name), skills);
+  if (!skill) return false;
+  return !skillAllowedForCwd(extensionScopesFromConfig(featureConfig(config)), skill, cwd);
+}
+
+/** The Skill tool result for a skill skillOutsideScope refuses. */
+export function skillOutsideScopeError(name) {
+  return `Error: skill "${name}" is not available in this project (its project scope excludes the current folder)`;
+}
+
 /**
  * Skills a session may see: not switched off, feature available, and — when
  * `cwd` is given — inside the skill's (or its plugin's) project scope. Without
@@ -260,8 +302,6 @@ export function collectPromptSkillsCached(cwd, config = null) {
 }
 // --- Global skill cache (mtime-based) ---
 const _skillsCache = new Map();
-const _mtimeCache = new Map();
-const _MTIME_TTL_MS = 2000;
 
 export function collectSkillsCached(cwd) {
   if (skillsDisabled()) return [];
@@ -273,32 +313,41 @@ export function collectSkillsCached(cwd) {
   skillsDirs.push(...pluginSkillDirs().map(({ dir }) => dir), ...builtinSkillDirs());
   // registry.json itself gates plugin add/remove: removal deletes the
   // plugin's skills dir (so no dir mtime advances), but saveRegistry()
-  // always rewrites this file. maxMtimeRecursive stats plain files directly.
+  // always rewrites this file. mtimeSignatureRecursive stats plain files directly.
   const registryPath = pluginRegistryPath();
   if (registryPath) skillsDirs.push(registryPath);
-  const mtime = mtimeWithTtl(_mtimeCache, key, skillsDirs, _MTIME_TTL_MS);
+  // Exact, un-timed gate: stat every call. The shallow watch list covers
+  // manifest edits and skill roots that do not exist yet.
+  const signature = `${mtimeSignatureRecursive(skillsDirs)}|${mtimeSignatureRecursive(pluginShallowWatchPaths(), 0)}`;
   const entry = _skillsCache.get(key);
-  if (entry && entry.mtime >= mtime) {
+  if (entry && entry.signature === signature) {
     return entry.value;
   }
   const skills = collectSkills(cwd);
-  _skillsCache.set(key, { value: skills, mtime });
+  _skillsCache.set(key, { value: skills, signature });
   capMapSize(_skillsCache);
   return skills;
 }
 export function invalidateSkillsCache(cwd) {
   void cwd;
   _skillsCache.clear();
-  _mtimeCache.clear();
 }
-/** Drop only the mtime TTL so the next call re-stats the skill roots while the
- *  cached list stays — lets a test prove the gate itself notices an edit. */
-export function invalidateSkillsMtimeGate() {
-  _mtimeCache.clear();
+
+/**
+ * Directory the model hands to external processes for a skill. A packaged
+ * desktop runtime reads built-in skills from inside `runtime.asar`, which only
+ * Electron can open; the build ships them as real files beside the archive
+ * under `runtime.asar.unpacked`, so a built-in skill's directory points there.
+ * Every other source keeps its own on-disk directory.
+ */
+export function skillExecutionDir(dir, source) {
+  if (source !== 'builtin') return dir;
+  return String(dir).replace(/([\\/])runtime\.asar(?=[\\/]|$)/, '$1runtime.asar.unpacked');
 }
 
 /**
- * Load full skill content plus its on-disk directory (for base-dir + ${MIXDOG_SKILL_DIR}).
+ * Load full skill content plus its on-disk directory (for base-dir + ${MIXDOG_SKILL_DIR};
+ * ${MIXDOG_SKILL_NODE} is resolved at render time in buildSkillResultEnvelope).
  */
 export function loadSkillResource(name, cwd) {
   const skillName = String(name || '').trim();
@@ -311,7 +360,7 @@ export function loadSkillResource(name, cwd) {
   try {
     return {
       content: parseSkillDocument(content).body,
-      dir: dirname(skill.filePath),
+      dir: skillExecutionDir(dirname(skill.filePath), skill.source),
       filePath: skill.filePath,
       source: skill.source || 'global',
       toolDependencies: skill.toolDependencies || [],
@@ -335,6 +384,10 @@ export function buildSkillResultEnvelope(name, content, skillDir) {
   const escapedName = escapeSkillXmlText(name);
   let body = String(content == null ? '' : content);
   let dirLine = '';
+  // `${MIXDOG_SKILL_NODE}` runs a bundled script on this daemon's own runtime
+  // (plain node cannot load runtime internals from a packaged archive). It is
+  // one shell-neutral command name that model shells find on their PATH.
+  body = body.replace(/\$\{MIXDOG_SKILL_NODE\}/g, SKILL_LAUNCHER_COMMAND);
   if (skillDir) {
     const normDir = String(skillDir).replace(/\\/g, '/');
     body = body.replace(/\$\{MIXDOG_SKILL_DIR\}/g, normDir);

package/src/runtime/agent/orchestrator/mcp/client-config.mjs

@@ -3,6 +3,8 @@
  * kind, URL policy, env expansion, stdio environment, HTTP headers, timeouts,
  * and the log scrubbing that keeps credentials out of connection messages.
  */
+import { createHash } from 'node:crypto';
+import { rememberMcpToolIdentity } from '../../../shared/tool-primitives.mjs';
 
 /** Known auto-detect targets: the discovery-advert service name and the MCP
  *  endpoint path on its port.
@@ -15,8 +17,16 @@ export const AUTO_DETECT_PORTS = {
   'mixdog-memory': { discovery: 'memory', endpoint: '/mcp' },
 };
 const DEFAULT_MCP_CALL_TIMEOUT_MS = 120000;
-// Per-server STARTUP handshake budget (connect + listTools): 10s.
-const DEFAULT_MCP_STARTUP_TIMEOUT_MS = 10000;
+// Per-server STARTUP handshake budget (connect + paginated listTools): 30s.
+// Cold npx/uvx wrappers routinely need well over 10s to install and boot.
+const DEFAULT_MCP_STARTUP_TIMEOUT_MS = 30000;
+// Hard ceiling for a request that keeps reporting progress (each progress
+// notification resets the per-call timeout, this caps the total): 30min.
+const DEFAULT_MCP_MAX_TOTAL_TIMEOUT_MS = 1_800_000;
+// Largest delay setTimeout honours; anything larger fires after 1ms. Used as
+// the SDK request timeout when our own call timeout is disabled, so the SDK's
+// built-in 60s default never applies.
+export const MCP_MAX_TIMER_MS = 2_147_483_647;
 
 function isLoopbackMcpHost(hostname) {
   const host = String(hostname || '')
@@ -100,30 +110,106 @@ export function scrubMcpConnectionMessage(value, cfg = {}) {
 }
 
 /**
- * Expand `${VAR}` and `${env:VAR}` references in string values using the
- * provided env map (defaults to process.env). Recurses into arrays/objects.
- * Unknown vars expand to an empty string. No shell execution.
+ * Expand `${VAR}`, `${env:VAR}` and `${VAR:-default}` references in string
+ * values using the provided env map (defaults to process.env). Recurses into
+ * arrays/objects. The default (possibly empty) applies only when the variable
+ * is unset, and runs to the first `}`. An unset variable without a default
+ * expands to an empty string and, when `missing` (a Set) is given, its name is
+ * recorded there. No shell execution.
  */
-export function expandEnvVars(value, env = process.env) {
+export function expandEnvVars(value, env = process.env, missing) {
   if (typeof value === 'string') {
-    return value.replace(/\$\{(?:env:)?([A-Za-z_][A-Za-z0-9_]*)\}/g, (_m, name) => {
+    return value.replace(/\$\{(?:env:)?([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (_m, name, fallback) => {
       const v = env?.[name];
-      return v == null ? '' : String(v);
+      if (v != null) return String(v);
+      if (fallback !== undefined) return fallback;
+      missing?.add(name);
+      return '';
     });
   }
   if (Array.isArray(value)) {
-    return value.map((v) => expandEnvVars(v, env));
+    return value.map((v) => expandEnvVars(v, env, missing));
   }
   if (value && typeof value === 'object') {
     const out = {};
     for (const [k, v] of Object.entries(value)) {
-      out[k] = expandEnvVars(v, env);
+      out[k] = expandEnvVars(v, env, missing);
     }
     return out;
   }
   return value;
 }
 
+/**
+ * Names (deduplicated, first-seen order) of variables a server config needs
+ * that are unset: `${VAR}` references without a default in command, args,
+ * env, url, headers and cwd, plus the variables named directly by
+ * `bearer_token_env_var`, `env_http_headers` values and `env_vars`. Names
+ * only — never values.
+ */
+export function findMissingMcpEnvVars(cfg = {}, env = process.env) {
+  const missing = new Set();
+  expandEnvVars([cfg.command, cfg.args, cfg.env, cfg.url, cfg.headers, cfg.cwd], env, missing);
+  const named = [
+    cfg.bearer_token_env_var,
+    ...(cfg.env_http_headers && typeof cfg.env_http_headers === 'object' && !Array.isArray(cfg.env_http_headers)
+      ? Object.values(cfg.env_http_headers)
+      : []),
+    ...(Array.isArray(cfg.env_vars) ? cfg.env_vars : []),
+  ];
+  for (const value of named) {
+    const name = typeof value === 'string' ? value.trim() : '';
+    if (name && envValue(env, name) == null) missing.add(name);
+  }
+  return [...missing];
+}
+
+// Windows variable names are case-insensitive.
+function envValue(env, name) {
+  if (process.platform !== 'win32') return env?.[name];
+  const actual = Object.keys(env || {}).find((key) => key.toLowerCase() === name.toLowerCase());
+  return actual ? env[actual] : undefined;
+}
+
+// Provider tool names: at most 64 characters of [A-Za-z0-9_-] (the strictest
+// limit among the providers Mixdog talks to).
+const PROVIDER_TOOL_NAME_MAX = 64;
+const PROVIDER_TOOL_NAME_RE = /^[A-Za-z0-9_-]+$/;
+const KEPT_SERVER_PART_MAX = 40;
+
+/**
+ * `mcp__<server>__<tool>` when that already fits provider limits (unchanged
+ * for every name that fits today). Otherwise a deterministic short form:
+ * the server part kept when it is safe (sanitized and cut short when not),
+ * the tool part sanitized and cut, and a hash of the full name appended so
+ * distinct tools never meet. Callers keep the original tool name alongside
+ * to dispatch the call.
+ */
+export function providerSafeMcpToolName(serverName, toolName) {
+  const server = String(serverName || '');
+  const tool = String(toolName || '');
+  const full = `mcp__${server}__${tool}`;
+  if (full.length <= PROVIDER_TOOL_NAME_MAX && PROVIDER_TOOL_NAME_RE.test(full)) return full;
+  const hash = createHash('sha1').update(full).digest('hex').slice(0, 8);
+  const serverPart =
+    /^[A-Za-z0-9-]+(?:_[A-Za-z0-9-]+)*$/.test(server) && server.length <= KEPT_SERVER_PART_MAX
+      ? server
+      : server
+          .replace(/[^A-Za-z0-9-]+/g, '-')
+          .replace(/^-+|-+$/g, '')
+          .slice(0, 24)
+          .replace(/-+$/, '') || 'server';
+  const room = PROVIDER_TOOL_NAME_MAX - `mcp__${serverPart}__`.length - hash.length - 1;
+  const toolPart = tool
+    .replace(/[^A-Za-z0-9_-]+/g, '_')
+    .slice(0, Math.max(0, room))
+    .replace(/_+$/, '');
+  const safe = `mcp__${serverPart}__${toolPart ? `${toolPart}_` : ''}${hash}`;
+  // Name-only consumers in this process (display, guards) resolve it back.
+  rememberMcpToolIdentity(safe, server, tool);
+  return safe;
+}
+
 const DEFAULT_STDIO_ENV_KEYS =
   process.platform === 'win32'
     ? [
@@ -204,8 +290,9 @@ export function resolveMcpTransportKind(cfg) {
 // (e.g. a busy editor) must not stall a tool call indefinitely. Genuinely
 // long-running tools can raise/disable it via MIXDOG_MCP_CALL_TIMEOUT_MS or a
 // per-server timeoutMs/callTimeoutMs config value (0/off/none/false disables).
-// On expiry we close the transport so the next dispatch reconnects fresh, but
-// we do not retry the timed-out call automatically (avoids side-effect dupes).
+// On expiry only the timed-out request is cancelled (notifications/cancelled);
+// the server and its other in-flight calls stay up, and the timed-out call is
+// never retried automatically (avoids side-effect dupes).
 export function resolveMcpCallTimeoutMs(cfg = {}, env = process.env) {
   const raw =
     cfg?.timeoutMs ?? cfg?.timeout_ms ?? cfg?.callTimeoutMs ?? cfg?.call_timeout_ms ?? env?.MIXDOG_MCP_CALL_TIMEOUT_MS;
@@ -213,11 +300,42 @@ export function resolveMcpCallTimeoutMs(cfg = {}, env = process.env) {
   if (typeof raw === 'string' && /^(0|off|none|false)$/i.test(raw.trim())) return 0;
   const parsed = Number(raw);
   if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_MCP_CALL_TIMEOUT_MS;
-  return Math.round(parsed);
+  return Math.min(Math.round(parsed), MCP_MAX_TIMER_MS);
+}
+
+// Total cap for a call whose server keeps reporting progress. Default 30min.
+// Per-server override: maxTotalTimeoutMs / max_total_timeout_ms. Global env:
+// MIXDOG_MCP_MAX_TOTAL_TIMEOUT_MS. 0/off/none/false removes the cap.
+export function resolveMcpMaxTotalTimeoutMs(cfg = {}, env = process.env) {
+  const raw = cfg?.maxTotalTimeoutMs ?? cfg?.max_total_timeout_ms ?? env?.MIXDOG_MCP_MAX_TOTAL_TIMEOUT_MS;
+  if (raw == null || raw === '' || raw === false) return DEFAULT_MCP_MAX_TOTAL_TIMEOUT_MS;
+  if (raw === 0 || (typeof raw === 'string' && /^(0|off|none|false)$/i.test(raw.trim()))) return 0;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_MCP_MAX_TOTAL_TIMEOUT_MS;
+  return Math.min(Math.round(parsed), MCP_MAX_TIMER_MS);
+}
+
+/**
+ * The effective limits of one MCP request:
+ *  - callTimeoutMs: our per-call timeout (0 = disabled), reset on progress;
+ *  - sdkTimeoutMs: what the SDK gets as `timeout` — the call timeout, or the
+ *    largest timer when disabled so the SDK's 60s default never applies;
+ *  - maxTotalTimeoutMs: the progress-reset ceiling (never below the call
+ *    timeout), or undefined when the call is unbounded or the cap is off.
+ */
+export function resolveMcpRequestTimeouts(cfg = {}, env = process.env) {
+  const callTimeoutMs = resolveMcpCallTimeoutMs(cfg, env);
+  if (!(callTimeoutMs > 0)) return { callTimeoutMs: 0, sdkTimeoutMs: MCP_MAX_TIMER_MS, maxTotalTimeoutMs: undefined };
+  const cap = resolveMcpMaxTotalTimeoutMs(cfg, env);
+  return {
+    callTimeoutMs,
+    sdkTimeoutMs: callTimeoutMs,
+    maxTotalTimeoutMs: cap > 0 ? Math.max(cap, callTimeoutMs) : undefined,
+  };
 }
 
 // MCP per-server STARTUP timeout: bounds the connect + listTools handshake so a
-// slow or hung server can't stall boot or the first turn. Default 10s.
+// slow or hung server can't stall boot or the first turn. Default 30s.
 // Per-server override: startupTimeoutMs / startupTimeoutSec. Global
 // env: MIXDOG_MCP_STARTUP_TIMEOUT_MS. A value of 0/off/none/false disables it.
 export function resolveMcpStartupTimeoutMs(cfg = {}, env = process.env) {
@@ -235,5 +353,5 @@ export function resolveMcpStartupTimeoutMs(cfg = {}, env = process.env) {
   if (raw === 0 || (typeof raw === 'string' && /^(0|off|none|false)$/i.test(raw.trim()))) return 0;
   const parsed = Number(raw) * scale;
   if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_MCP_STARTUP_TIMEOUT_MS;
-  return Math.round(parsed);
+  return Math.min(Math.round(parsed), MCP_MAX_TIMER_MS);
 }

package/src/runtime/agent/orchestrator/mcp/client-handshake.mjs

@@ -4,14 +4,44 @@
  * and a discovery advert that refused the connection is distrusted.
  */
 import { markServiceUnreachable, isConnRefuseError } from '../../../shared/service-discovery.mjs';
-import { resolveMcpStartupTimeoutMs } from './client-config.mjs';
+import { MCP_MAX_TIMER_MS, resolveMcpStartupTimeoutMs } from './client-config.mjs';
+import { appendMcpStderrTail } from './client-transport.mjs';
 
-async function performHandshake(client, transport) {
-  await client.connect(transport);
+// tools/list pagination bounds: a server that never stops handing out cursors
+// (or repeats one) cannot loop the client forever.
+const MAX_MCP_TOOL_PAGES = 100;
+
+/**
+ * Every tool of a server: follows `nextCursor` until it is exhausted, repeats,
+ * or MAX_MCP_TOOL_PAGES is reached. A page with an invalid shape is returned
+ * as-is so the caller's shape validation reports it.
+ * The SDK rebuilds its output validators from each page alone, so after a
+ * paginated listing they are rebuilt once from every page's tools.
+ */
+export async function listAllMcpTools(client, requestOptions = undefined) {
+  const tools = [];
+  const seen = new Set();
+  let cursor = null;
+  let pages = 0;
+  for (; pages < MAX_MCP_TOOL_PAGES; pages += 1) {
+    const result = await client.listTools(cursor ? { cursor } : undefined, requestOptions);
+    if (!result || !Array.isArray(result.tools)) return result;
+    tools.push(...result.tools);
+    const next = typeof result.nextCursor === 'string' && result.nextCursor ? result.nextCursor : null;
+    if (!next || seen.has(next)) break;
+    seen.add(next);
+    cursor = next;
+  }
+  if (pages > 0) client.cacheToolMetadata?.(tools);
+  return { tools };
+}
+
+async function performHandshake(client, transport, requestOptions) {
+  await client.connect(transport, requestOptions);
   const instructionsRaw = typeof client.getInstructions === 'function' ? client.getInstructions() : undefined;
   const instructions = typeof instructionsRaw === 'string' ? instructionsRaw.trim() : '';
   const capabilities = client.getServerCapabilities?.() || {};
-  const toolsResult = capabilities.tools ? await client.listTools() : { tools: [] };
+  const toolsResult = capabilities.tools ? await listAllMcpTools(client, requestOptions) : { tools: [] };
   return { instructions, toolsResult, capabilities };
 }
 
@@ -28,12 +58,24 @@ function startupTimeoutError(name, startupTimeoutMs) {
  * boot or the first turn. On expiry the pending transport/child is torn down
  * (nothing leaks) and this server fails like any other connect failure — the
  * parallel Promise.allSettled means other servers are unaffected.
- * Returns { instructions, toolsResult, capabilities }.
+ * The SDK's per-request timeout follows the same budget (its own 60s default
+ * would otherwise cut a longer or disabled budget short). Failures carry the
+ * server's stderr tail. Returns { instructions, toolsResult, capabilities }.
  */
-export async function runBoundedHandshake({ name, cfg, client, transport, autoDetectAdvert, closeServer }) {
+export async function runBoundedHandshake({
+  name,
+  cfg,
+  client,
+  transport,
+  autoDetectAdvert,
+  closeServer,
+  stderrTail = () => '',
+}) {
   const startupTimeoutMs = resolveMcpStartupTimeoutMs(cfg);
   const guard = { timer: null, timedOut: false };
-  const handshake = performHandshake(client, transport);
+  const handshake = performHandshake(client, transport, {
+    timeout: startupTimeoutMs > 0 ? startupTimeoutMs : MCP_MAX_TIMER_MS,
+  });
   try {
     if (startupTimeoutMs <= 0) return await handshake;
     const deadline = new Promise((_, rej) => {
@@ -63,7 +105,12 @@ export async function runBoundedHandshake({ name, cfg, client, transport, autoDe
       // Never let the late handshake settle into an unhandled rejection.
       handshake.catch(() => {});
     }
-    throw err;
+    const tail = stderrTail();
+    if (tail && err instanceof Error) {
+      err.message = appendMcpStderrTail(err.message, tail);
+      throw err;
+    }
+    throw tail ? new Error(appendMcpStderrTail(String(err), tail)) : err;
   } finally {
     if (guard.timer) clearTimeout(guard.timer);
   }

package/src/runtime/agent/orchestrator/mcp/client-transport.mjs

@@ -7,6 +7,7 @@ import { readServicePort } from '../../../shared/service-discovery.mjs';
 import {
   AUTO_DETECT_PORTS,
   expandEnvVars,
+  findMissingMcpEnvVars,
   mcpUrlForLog,
   normalizeMcpTransportUrl,
   resolveMcpHttpHeaders,
@@ -32,19 +33,83 @@ function resolveAutoDetectUrl(name, cfg) {
   return { url: `http://127.0.0.1:${port}${spec.endpoint}`, advert: { service: spec.discovery, port } };
 }
 
+// Bounded tail of a stdio server's stderr, kept for failure messages (a server
+// that dies at startup or mid-session usually says why on stderr).
+const MCP_STDERR_TAIL_CHARS = 4096;
+const noStderrTail = () => '';
+
+/** Append a server's stderr tail to a failure message (unchanged when empty). */
+export function appendMcpStderrTail(message, tail) {
+  const text = String(tail || '').trim();
+  return text ? `${message}\n--- server stderr (tail) ---\n${text}` : String(message);
+}
+
 function requestInitFor(cfg) {
   const headers = resolveMcpHttpHeaders(cfg);
   return headers && Object.keys(headers).length > 0 ? { requestInit: { headers } } : undefined;
 }
 
-/** Returns { transport, autoDetectAdvert }. */
-export function createMcpTransport({ name, cfg, sdk, log }) {
+// The SDK's WebSocket transport opens its socket without a way to set request
+// headers. This subclass changes only socket creation: Node's WebSocket takes
+// `{ protocols, headers }`; the guard and event wiring match the stock start().
+function createHeaderWebSocketTransport(Base, messageSchema, url, headers) {
+  return new (class extends Base {
+    start() {
+      if (this._socket) {
+        throw new Error(
+          'WebSocketClientTransport already started! If using Client class, note that connect() calls start() automatically.'
+        );
+      }
+      return new Promise((resolve, reject) => {
+        this._socket = new globalThis.WebSocket(this._url, { protocols: 'mcp', headers });
+        this._socket.onerror = (event) => {
+          const error = 'error' in event ? event.error : new Error(`WebSocket error: ${JSON.stringify(event)}`);
+          reject(error);
+          this.onerror?.(error);
+        };
+        this._socket.onopen = () => resolve();
+        this._socket.onclose = () => this.onclose?.();
+        this._socket.onmessage = (event) => {
+          let message;
+          try {
+            message = messageSchema.parse(JSON.parse(event.data));
+          } catch (error) {
+            this.onerror?.(error);
+            return;
+          }
+          this.onmessage?.(message);
+        };
+      });
+    }
+  })(url);
+}
+/** Returns { transport, autoDetectAdvert, stderrTail, warnings } — stderrTail()
+ *  is the last ~4 KB of a stdio server's (scrubbed) stderr, '' for remote
+ *  transports. `strictEnv` (the caller passes it for plugin-declared servers)
+ *  makes unset variables without a default fail the server; otherwise they
+ *  expand to empty and are reported in `warnings` (names only). */
+export function createMcpTransport({ name, cfg, sdk, log, strictEnv }) {
   const { StdioClientTransport, StreamableHTTPClientTransport, SSEClientTransport, WebSocketClientTransport } = sdk;
   const kind = resolveMcpTransportKind(cfg);
+  const warnings = [];
+  if (kind !== 'autoDetect') {
+    const missing = findMissingMcpEnvVars(cfg);
+    if (missing.length) {
+      const message = `missing environment variable(s): ${missing.join(', ')}`;
+      if (strictEnv === true) throw new Error(message);
+      warnings.push(message);
+      log(`[mcp-client] "${name}": ${message}\n`);
+    }
+  }
   if (kind === 'autoDetect') {
     const { url, advert } = resolveAutoDetectUrl(name, cfg);
     log(`[mcp-client] Connecting "${name}" via autoDetect HTTP: ${url}\n`);
-    return { transport: new StreamableHTTPClientTransport(new URL(url)), autoDetectAdvert: advert };
+    return {
+      transport: new StreamableHTTPClientTransport(new URL(url)),
+      autoDetectAdvert: advert,
+      stderrTail: noStderrTail,
+      warnings,
+    };
   }
   if (kind === 'http' || kind === 'sse') {
     const Transport = kind === 'http' ? StreamableHTTPClientTransport : SSEClientTransport;
@@ -54,26 +119,39 @@ export function createMcpTransport({ name, cfg, sdk, log }) {
     return {
       transport: opts ? new Transport(new URL(url), opts) : new Transport(new URL(url)),
       autoDetectAdvert: null,
+      stderrTail: noStderrTail,
+      warnings,
     };
   }
   if (kind === 'ws') {
-    // WebSocketClientTransport ctor takes only a URL; headers are ignored.
     const url = normalizeMcpTransportUrl(expandEnvVars(String(cfg.url ?? '')), 'ws');
+    const opts = requestInitFor(cfg);
     log(`[mcp-client] Connecting "${name}" via WebSocket: ${mcpUrlForLog(url)}\n`);
-    return { transport: new WebSocketClientTransport(new URL(url)), autoDetectAdvert: null };
+    const transport = opts
+      ? createHeaderWebSocketTransport(
+          WebSocketClientTransport,
+          sdk.JSONRPCMessageSchema,
+          new URL(url),
+          opts.requestInit.headers
+        )
+      : new WebSocketClientTransport(new URL(url));
+    return { transport, autoDetectAdvert: null, stderrTail: noStderrTail, warnings };
   }
   if (kind === 'stdio') {
     const transport = new StdioClientTransport({
       command: expandEnvVars(String(cfg.command ?? '')),
       args: Array.isArray(cfg.args) ? expandEnvVars(cfg.args) : cfg.args,
-      cwd: cfg.cwd,
+      cwd: cfg.cwd == null ? cfg.cwd : expandEnvVars(String(cfg.cwd)),
       env: resolveMcpStdioEnvironment(cfg),
       stderr: cfg.stderr ?? 'pipe',
     });
+    let tail = '';
     transport.stderr?.on?.('data', (chunk) => {
-      log(`[mcp:${name}:stderr] ${scrubMcpConnectionMessage(chunk, cfg)}`);
+      const text = scrubMcpConnectionMessage(chunk, cfg);
+      tail = (tail + text).slice(-MCP_STDERR_TAIL_CHARS);
+      log(`[mcp:${name}:stderr] ${text}`);
     });
-    return { transport, autoDetectAdvert: null };
+    return { transport, autoDetectAdvert: null, stderrTail: () => tail.trim(), warnings };
   }
   throw new Error(
     `Invalid config for "${name}": need autoDetect, type (stdio/http/sse/ws), url (http), or command (stdio)`