@haven_ai/connect 0.1.2-alpha → 0.1.4-alpha

package/dist/index.cjs

@@ -207,14 +207,156 @@ async function restrictPermissions(path, mode, warn) {
     );
   }
 }
+var MCP_RUNTIME_MANIFEST = {
+  mcpPackage: "@haven_ai/mcp",
+  mcpVersion: mcp.MCP_VERSION,
+  sdkPackage: "@haven_ai/sdk",
+  sdkVersion: "0.1.7",
+  signerPackage: "@haven_ai/signer",
+  signerVersion: "0.1.0-alpha",
+  minimumNodeVersion: "20.0.0",
+  supportedClients: ["codex-cli", "codex-desktop", "claude-code"],
+  requiredTools: mcp.registeredToolNames()
+};
+function mcpPackageSpec() {
+  return `${MCP_RUNTIME_MANIFEST.mcpPackage}@${MCP_RUNTIME_MANIFEST.mcpVersion}`;
+}
+function sdkPackageSpec() {
+  return `${MCP_RUNTIME_MANIFEST.sdkPackage}@${MCP_RUNTIME_MANIFEST.sdkVersion}`;
+}
+function signerPackageSpec() {
+  return `${MCP_RUNTIME_MANIFEST.signerPackage}@${MCP_RUNTIME_MANIFEST.signerVersion}`;
+}
+
+// src/runtime-registry.ts
+var RUNTIME_PROFILES = {
+  "claude-code": {
+    id: "claude-code",
+    label: "Claude Code",
+    restartMode: "restart-session",
+    canWriteRuntimeConfig: true
+  },
+  "codex-cli": {
+    id: "codex-cli",
+    label: "Codex CLI",
+    restartMode: "restart-session",
+    canWriteRuntimeConfig: true
+  },
+  "codex-desktop": {
+    id: "codex-desktop",
+    label: "Codex Desktop",
+    restartMode: "restart-session",
+    canWriteRuntimeConfig: true
+  },
+  cursor: {
+    id: "cursor",
+    label: "Cursor",
+    restartMode: "hot-reload",
+    canWriteRuntimeConfig: true
+  },
+  vscode: {
+    id: "vscode",
+    label: "VS Code",
+    restartMode: "hot-reload",
+    canWriteRuntimeConfig: true
+  },
+  "vscode-insiders": {
+    id: "vscode-insiders",
+    label: "VS Code Insiders",
+    restartMode: "hot-reload",
+    canWriteRuntimeConfig: true
+  },
+  "claude-desktop": {
+    id: "claude-desktop",
+    label: "Claude Desktop",
+    restartMode: "restart-app",
+    canWriteRuntimeConfig: true
+  },
+  other: {
+    id: "other",
+    label: "Other agent runtime",
+    restartMode: "manual",
+    canWriteRuntimeConfig: false
+  }
+};
+var RUNTIME_ALIASES = {
+  claude: "claude-code",
+  "claude-code": "claude-code",
+  claudecode: "claude-code",
+  "claude_code": "claude-code",
+  codex: "codex-cli",
+  "codex-cli": "codex-cli",
+  codexcli: "codex-cli",
+  "codex_cli": "codex-cli",
+  "codex-desktop": "codex-desktop",
+  "codex_desktop": "codex-desktop",
+  codexdesktop: "codex-desktop",
+  "codex-app": "codex-desktop",
+  "codex_app": "codex-desktop",
+  codexapp: "codex-desktop",
+  cursor: "cursor",
+  vscode: "vscode",
+  "vs-code": "vscode",
+  "vs_code": "vscode",
+  code: "vscode",
+  "vscode-insiders": "vscode-insiders",
+  "vscode_insiders": "vscode-insiders",
+  vscodeinsiders: "vscode-insiders",
+  "vs-code-insiders": "vscode-insiders",
+  "code-insiders": "vscode-insiders",
+  insiders: "vscode-insiders",
+  "claude-desktop": "claude-desktop",
+  "claude_desktop": "claude-desktop",
+  claudesktop: "claude-desktop",
+  desktop: "claude-desktop",
+  other: "other",
+  manual: "other"
+};
+function runtimeProfile(runtime, env = process.env) {
+  return RUNTIME_PROFILES[normalizeRuntime(runtime, env)];
+}
+function normalizeRuntime(runtime, env = process.env) {
+  const explicit = normalizeRuntimeName(runtime);
+  if (explicit) return explicit;
+  return detectRuntime(env) ?? "other";
+}
+function restartRequiredForRuntime(runtime, env = process.env) {
+  const mode = runtimeProfile(runtime, env).restartMode;
+  return mode === "restart-session" || mode === "restart-app";
+}
+function runtimeRequiresHardRestart(runtime) {
+  return runtime === "claude-desktop" || runtime === "codex-desktop";
+}
+function normalizeRuntimeName(runtime) {
+  const key = runtime?.trim().toLowerCase();
+  if (!key) return null;
+  return RUNTIME_ALIASES[key.replace(/\s+/g, "-")] ?? null;
+}
+function detectRuntime(env) {
+  if (env.CLAUDECODE || env.CLAUDE_CODE || env.CLAUDECODE_CWD) return "claude-code";
+  if (env.CODEX_SANDBOX || env.CODEX_HOME || env.CODEX_CWD) return "codex-cli";
+  if (env.VSCODE_CWD || env.VSCODE_IPC_HOOK_CLI || env.TERM_PROGRAM === "vscode") return "vscode";
+  return null;
+}
+
+// src/config-writers.ts
+var InvalidCodexTomlError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidCodexTomlError";
+  }
+};
 async function writeRuntimeConfig(input) {
   switch (input.runtime) {
     case "codex-cli":
+    case "codex-desktop":
       return writeCodexConfig(input);
     case "cursor":
       return writeJsonRuntimeConfig(input, cursorConfigPath(input.homeDir), "mcpServers");
     case "vscode":
       return writeJsonRuntimeConfig(input, vscodeConfigPath(input.homeDir), "servers");
+    case "vscode-insiders":
+      return writeJsonRuntimeConfig(input, vscodeInsidersConfigPath(input.homeDir), "servers");
     case "claude-desktop":
       return writeJsonRuntimeConfig(input, claudeDesktopConfigPath(input.homeDir), "mcpServers");
     default:
@@ -232,7 +374,7 @@ async function writeRuntimeConfig(input) {
   }
 }
 function buildHostedServer(hostedMcpUrl, apiKey, runtime) {
-  if (runtime === "vscode") {
+  if (runtime === "vscode" || runtime === "vscode-insiders") {
     return {
       type: "http",
       url: hostedMcpUrl,
@@ -249,7 +391,7 @@ function buildSignerServer(signerPath, runtime) {
     command: "npx",
     args: ["-y", signerPackageName(), "--credentials", signerPath]
   };
-  if (runtime === "vscode") return { type: "stdio", ...server };
+  if (runtime === "vscode" || runtime === "vscode-insiders") return { type: "stdio", ...server };
   return server;
 }
 function mergeJsonMcpConfig(existingJson, serverRoot, hostedServer, signerServer) {
@@ -264,18 +406,21 @@ function mergeJsonMcpConfig(existingJson, serverRoot, hostedServer, signerServer
   return `${JSON.stringify(config, null, 2)}
 `;
 }
-function mergeCodexToml(existingToml, identityPath, signerPath) {
-  let next = removeTomlTable(removeTomlTable(existingToml, "mcp_servers.haven"), "mcp_servers.haven_signer");
+function mergeCodexToml(existingToml, localMcpCommand) {
+  let next = removeTomlTableTree(removeTomlTableTree(existingToml, "mcp_servers.haven"), "mcp_servers.haven_signer");
   next = next.trimEnd();
   const block = [
     "[mcp_servers.haven]",
-    'command = "npx"',
-    `args = ["-y", ${tomlString(localMcpPackageName())}, "--identity", ${tomlString(identityPath)}, "--signer", ${tomlString(signerPath)}]`
+    `command = ${tomlString(localMcpCommand)}`,
+    "args = []",
+    "startup_timeout_sec = 120"
   ].join("\n");
-  return `${next ? `${next}
+  validateCodexToml(block, "Generated Codex Haven config");
+  const merged = `${next ? `${next}
 
 ` : ""}${block}
 `;
+  return merged;
 }
 async function writeJsonRuntimeConfig(input, target, serverRoot) {
   try {
@@ -315,32 +460,39 @@ async function writeCodexConfig(input) {
   const target = codexConfigPath(input.homeDir);
   try {
     const existing = await readOptional(target);
-    const merged = mergeCodexToml(existing ?? "", input.identityPath, input.signerPath);
+    if (!input.localMcpCommand) {
+      throw new Error("local MCP wrapper command is required");
+    }
+    const merged = mergeCodexToml(existing ?? "", input.localMcpCommand);
     await writeOwnerOnlyText(target, merged);
     return {
       hostedConfigured: false,
       signerConfigured: true,
       localMcpConfigured: true,
       runtimeMcpMode: "local_stdio",
-      target: "Codex CLI config",
+      target: configTargetLabel(input.runtime),
       changed: existing !== merged,
       restartRequired: true,
       messages: [
-        "Updated local Haven MCP entry in Codex CLI config.",
-        "After Haven approval, restart Codex normally so it can load Haven tools."
+        `Updated local Haven MCP entry in ${configTargetLabel(input.runtime)}.`,
+        // Codex Desktop loads MCP servers at app launch; Codex CLI typically
+        // picks them up in the next session. Branch the copy so desktop users
+        // get the unambiguous instruction.
+        runtimeRequiresHardRestart(input.runtime) ? "After Haven approval, restart Codex Desktop so it can load Haven tools." : "After Haven approval, Haven tools should appear in your next Codex message. If they don't, restart Codex to load them."
       ]
     };
   } catch (err) {
+    const invalidToml = err instanceof InvalidCodexTomlError;
     return {
       hostedConfigured: false,
       signerConfigured: false,
       localMcpConfigured: false,
       runtimeMcpMode: "local_stdio",
-      target: "Codex CLI config",
+      target: configTargetLabel(input.runtime),
       changed: false,
       restartRequired: true,
-      messages: [`Could not update Codex CLI config: ${err instanceof Error ? err.message : String(err)}`],
-      errorCode: "runtime_config_write_failed"
+      messages: [`Could not update ${configTargetLabel(input.runtime)}: ${err instanceof Error ? err.message : String(err)}`],
+      errorCode: invalidToml ? "codex_config_invalid" : "runtime_config_write_failed"
     };
   }
 }
@@ -364,24 +516,191 @@ function parseJsonObject(value) {
   }
   return parsed;
 }
-function removeTomlTable(toml, table) {
+function removeTomlTableTree(toml, table) {
   const lines = toml.split(/\r?\n/);
-  const start = `[${table}]`;
   const kept = [];
   let skipping = false;
   for (const line of lines) {
     const trimmed = line.trim();
-    if (trimmed === start) {
-      skipping = true;
-      continue;
-    }
-    if (skipping && trimmed.startsWith("[") && trimmed.endsWith("]")) {
-      skipping = false;
+    const tableName = tomlTableName(trimmed);
+    if (tableName) {
+      skipping = tableName === table || tableName.startsWith(`${table}.`);
+      if (skipping) continue;
     }
     if (!skipping) kept.push(line);
   }
   return kept.join("\n");
 }
+function tomlTableName(line) {
+  if (line.startsWith("[[") && line.endsWith("]]")) return line.slice(2, -2).trim();
+  if (line.startsWith("[") && line.endsWith("]")) return line.slice(1, -1).trim();
+  return null;
+}
+function validateCodexToml(toml, label = "Codex config") {
+  const lines = toml.split(/\r?\n/);
+  let pendingValue = null;
+  for (let index = 0; index < lines.length; index += 1) {
+    const raw = lines[index];
+    const line = stripTomlComment(raw).trim();
+    if (!line) continue;
+    if (pendingValue) {
+      pendingValue.value = `${pendingValue.value}
+${line}`;
+      if (hasBalancedTomlContainers(pendingValue.value)) {
+        if (!isTomlValue(pendingValue.value)) {
+          throw new InvalidCodexTomlError(`${label} has invalid TOML near line ${pendingValue.line}.`);
+        }
+        pendingValue = null;
+      }
+      continue;
+    }
+    if (isTomlTable(line)) continue;
+    const equalsIndex = line.indexOf("=");
+    if (equalsIndex <= 0) {
+      throw new InvalidCodexTomlError(`${label} has invalid TOML near line ${index + 1}.`);
+    }
+    const key = line.slice(0, equalsIndex).trim();
+    const value = line.slice(equalsIndex + 1).trim();
+    if (!isTomlKey(key)) {
+      throw new InvalidCodexTomlError(`${label} has invalid TOML near line ${index + 1}.`);
+    }
+    if (startsTomlContainer(value) && !hasBalancedTomlContainers(value)) {
+      pendingValue = { value, line: index + 1 };
+      continue;
+    }
+    if (!isTomlValue(value)) {
+      throw new InvalidCodexTomlError(`${label} has invalid TOML near line ${index + 1}.`);
+    }
+  }
+  if (pendingValue) {
+    throw new InvalidCodexTomlError(`${label} has invalid TOML near line ${pendingValue.line}.`);
+  }
+}
+function isTomlTable(line) {
+  const table = tomlTableName(line);
+  return Boolean(table && splitTomlDottedKey(table).every(isTomlKeyPart));
+}
+function isTomlKey(value) {
+  return splitTomlDottedKey(value).every(isTomlKeyPart);
+}
+function splitTomlDottedKey(value) {
+  const parts = [];
+  let current = "";
+  let quote = null;
+  let escaped = false;
+  for (let i = 0; i < value.length; i += 1) {
+    const char = value[i];
+    if (quote) {
+      current += char;
+      if (quote === '"' && char === "\\" && !escaped) {
+        escaped = true;
+        continue;
+      }
+      if (char === quote && !escaped) quote = null;
+      escaped = false;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      current += char;
+      continue;
+    }
+    if (char === ".") {
+      parts.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  parts.push(current.trim());
+  return quote ? [] : parts;
+}
+function isTomlKeyPart(value) {
+  return isTomlBareKey(value) || isTomlQuotedString(value);
+}
+function isTomlBareKey(value) {
+  return /^[A-Za-z0-9_-]+$/.test(value);
+}
+function isTomlValue(value) {
+  if (!value) return false;
+  if (isTomlQuotedString(value)) return true;
+  if (/^(true|false)$/i.test(value)) return true;
+  if (/^[+-]?(?:inf|nan)$/i.test(value)) return true;
+  if (/^[+-]?(?:0|[1-9][0-9_]*)(?:\.[0-9_]+)?(?:[eE][+-]?[0-9_]+)?$/.test(value)) return true;
+  if (/^\d{4}-\d{2}-\d{2}(?:[Tt ][0-9:.+-Zz]+)?$/.test(value)) return true;
+  if (value.startsWith("[") && value.endsWith("]") || value.startsWith("{") && value.endsWith("}")) {
+    return hasBalancedTomlContainers(value);
+  }
+  return false;
+}
+function startsTomlContainer(value) {
+  return value.startsWith("[") || value.startsWith("{");
+}
+function isTomlQuotedString(value) {
+  if (value.startsWith('"""') || value.startsWith("'''")) {
+    const marker = value.slice(0, 3);
+    return value.length >= 6 && value.endsWith(marker);
+  }
+  if ((!value.startsWith('"') || !value.endsWith('"')) && (!value.startsWith("'") || !value.endsWith("'"))) {
+    return false;
+  }
+  return hasBalancedTomlContainers(value);
+}
+function stripTomlComment(value) {
+  let quote = null;
+  let escaped = false;
+  for (let i = 0; i < value.length; i += 1) {
+    const char = value[i];
+    if (quote) {
+      if (quote === '"' && char === "\\" && !escaped) {
+        escaped = true;
+        continue;
+      }
+      if (char === quote && !escaped) quote = null;
+      escaped = false;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === "#") return value.slice(0, i);
+  }
+  return value;
+}
+function hasBalancedTomlContainers(value) {
+  const stack = [];
+  let quote = null;
+  let escaped = false;
+  for (let i = 0; i < value.length; i += 1) {
+    const char = value[i];
+    if (quote) {
+      if (quote === '"' && char === "\\" && !escaped) {
+        escaped = true;
+        continue;
+      }
+      if (char === quote && !escaped) quote = null;
+      escaped = false;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === "[" || char === "{") {
+      stack.push(char);
+      continue;
+    }
+    if (char === "]") {
+      if (stack.pop() !== "[") return false;
+      continue;
+    }
+    if (char === "}") {
+      if (stack.pop() !== "{") return false;
+    }
+  }
+  return stack.length === 0 && quote === null;
+}
 function tomlString(value) {
   return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
@@ -398,6 +717,13 @@ function vscodeConfigPath(homeDir = os.homedir()) {
   }
   return path.resolve(homeDir, ".config", "Code", "User", "mcp.json");
 }
+function vscodeInsidersConfigPath(homeDir = os.homedir()) {
+  if (os.platform() === "darwin") return path.resolve(homeDir, "Library", "Application Support", "Code - Insiders", "User", "mcp.json");
+  if (os.platform() === "win32") {
+    return path.resolve(process.env.APPDATA ?? path.join(homeDir, "AppData", "Roaming"), "Code - Insiders", "User", "mcp.json");
+  }
+  return path.resolve(homeDir, ".config", "Code - Insiders", "User", "mcp.json");
+}
 function claudeDesktopConfigPath(homeDir = os.homedir()) {
   if (os.platform() === "darwin") {
     return path.resolve(homeDir, "Library", "Application Support", "Claude", "claude_desktop_config.json");
@@ -409,10 +735,16 @@ function claudeDesktopConfigPath(homeDir = os.homedir()) {
 }
 function configTargetLabel(runtime) {
   switch (runtime) {
+    case "codex-cli":
+      return "Codex CLI config";
+    case "codex-desktop":
+      return "Codex Desktop config";
     case "cursor":
       return "Cursor MCP config";
     case "vscode":
       return "VS Code MCP config";
+    case "vscode-insiders":
+      return "VS Code Insiders MCP config";
     case "claude-desktop":
       return "Claude Desktop config";
     default:
@@ -420,10 +752,7 @@ function configTargetLabel(runtime) {
   }
 }
 function signerPackageName() {
-  return `@haven_ai/signer@${signer.SIGNER_VERSION}`;
-}
-function localMcpPackageName() {
-  return `@haven_ai/mcp@${mcp.MCP_VERSION}`;
+  return signerPackageSpec();
 }
 async function acknowledgeLocalMcpConsent(identityPath, signerPath, log) {
   try {
@@ -537,6 +866,72 @@ async function probeLocalSignerCredential(signerPath) {
     return false;
   }
 }
+async function probeLocalMcpTools(command, args, requiredTools, timeoutMs = 1e4) {
+  return new Promise((resolve6) => {
+    const child = child_process.spawn(command, args, { stdio: ["pipe", "pipe", "ignore"] });
+    let stdout = "";
+    let settled = false;
+    let sawInitialize = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      child.kill();
+      resolve6(result);
+    };
+    const timeout = setTimeout(() => finish({ status: "timeout" }), timeoutMs);
+    child.on("error", () => finish({ status: "process_error" }));
+    child.on("exit", (code) => {
+      if (!settled && code !== 0) finish({ status: "process_error" });
+    });
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString("utf8");
+      const lines = stdout.split(/\r?\n/);
+      stdout = lines.pop() ?? "";
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        let payload;
+        try {
+          payload = JSON.parse(trimmed);
+        } catch {
+          continue;
+        }
+        if (payload.error) {
+          finish({ status: "bad_response" });
+          return;
+        }
+        if (payload.id === 1 && !sawInitialize) {
+          sawInitialize = true;
+          writeJsonRpc(child, { jsonrpc: "2.0", method: "notifications/initialized", params: {} });
+          writeJsonRpc(child, { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} });
+          continue;
+        }
+        if (payload.id === 2) {
+          const tools = payload.result?.tools;
+          const toolNames = Array.isArray(tools) ? tools.map((tool) => tool && typeof tool === "object" && "name" in tool ? tool.name : void 0).filter((name) => typeof name === "string") : [];
+          const missing = requiredTools.filter((name) => !toolNames.includes(name));
+          finish({ status: missing.length === 0 ? "ok" : "missing_tools", toolNames });
+          return;
+        }
+      }
+    });
+    writeJsonRpc(child, {
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {
+        protocolVersion: "2025-06-18",
+        capabilities: {},
+        clientInfo: { name: "haven-connect-probe", version: "0.0.0" }
+      }
+    });
+  });
+}
+function writeJsonRpc(child, payload) {
+  child.stdin?.write(`${JSON.stringify(payload)}
+`);
+}
 function parseJsonRpcPayload(raw) {
   const trimmed = raw.trim();
   if (!trimmed) return null;
@@ -565,89 +960,160 @@ async function fetchWithTimeout(fetchImpl, url, init) {
     clearTimeout(timeout);
   }
 }
-
-// src/runtime-registry.ts
-var RUNTIME_PROFILES = {
-  "claude-code": {
-    id: "claude-code",
-    label: "Claude Code",
-    restartMode: "restart-session",
-    canWriteRuntimeConfig: true
-  },
-  "codex-cli": {
-    id: "codex-cli",
-    label: "Codex CLI",
-    restartMode: "restart-session",
-    canWriteRuntimeConfig: true
-  },
-  cursor: {
-    id: "cursor",
-    label: "Cursor",
-    restartMode: "hot-reload",
-    canWriteRuntimeConfig: true
-  },
-  vscode: {
-    id: "vscode",
-    label: "VS Code",
-    restartMode: "hot-reload",
-    canWriteRuntimeConfig: true
-  },
-  "claude-desktop": {
-    id: "claude-desktop",
-    label: "Claude Desktop",
-    restartMode: "restart-app",
-    canWriteRuntimeConfig: true
-  },
-  other: {
-    id: "other",
-    label: "Other agent runtime",
-    restartMode: "manual",
-    canWriteRuntimeConfig: false
+var execFileAsync = util.promisify(child_process.execFile);
+var UnsupportedNodeVersionError = class extends Error {
+  code = "local_mcp_unsupported_node_version";
+  constructor(nodeVersion, minimumNodeVersion) {
+    super(`Node.js ${nodeVersion} is not supported. Haven local MCP requires Node.js >=${minimumNodeVersion}.`);
+    this.name = "UnsupportedNodeVersionError";
   }
 };
-var RUNTIME_ALIASES = {
-  claude: "claude-code",
-  "claude-code": "claude-code",
-  claudecode: "claude-code",
-  "claude_code": "claude-code",
-  codex: "codex-cli",
-  "codex-cli": "codex-cli",
-  codexcli: "codex-cli",
-  "codex_cli": "codex-cli",
-  cursor: "cursor",
-  vscode: "vscode",
-  "vs-code": "vscode",
-  "vs_code": "vscode",
-  code: "vscode",
-  "claude-desktop": "claude-desktop",
-  "claude_desktop": "claude-desktop",
-  claudesktop: "claude-desktop",
-  desktop: "claude-desktop",
-  other: "other",
-  manual: "other"
-};
-function runtimeProfile(runtime, env = process.env) {
-  return RUNTIME_PROFILES[normalizeRuntime(runtime, env)];
+async function prepareLocalMcpRuntime(input, deps = {}) {
+  assertSupportedNodeVersion(input.nodeVersion);
+  const homeDir = input.homeDir ?? os.homedir();
+  const runtimeDirectory = path.resolve(homeDir, ".haven", "mcp-runtime", MCP_RUNTIME_MANIFEST.mcpVersion);
+  const npmCacheDirectory = path.resolve(homeDir, ".haven", "npm-cache");
+  const cliPath = path.join(runtimeDirectory, "node_modules", "@haven_ai", "mcp", "dist", "cli.js");
+  const messages = [];
+  await promises.mkdir(runtimeDirectory, { recursive: true, mode: 448 });
+  await promises.chmod(runtimeDirectory, 448).catch(() => void 0);
+  await promises.mkdir(npmCacheDirectory, { recursive: true, mode: 448 });
+  await promises.chmod(npmCacheDirectory, 448).catch(() => void 0);
+  if (await installedRuntimeMatches(runtimeDirectory, cliPath)) {
+    messages.push(`Using existing local Haven MCP runtime ${mcpPackageSpec()}.`);
+  } else {
+    await installRuntimePackages(runtimeDirectory, npmCacheDirectory, deps.runCommand);
+    messages.push(`Installed local Haven MCP runtime ${mcpPackageSpec()}.`);
+  }
+  await assertFileExists(cliPath, "local Haven MCP CLI");
+  const wrapperPath = path.join(input.credentialDirectory, "bin", "haven-mcp");
+  await writeWrapper({
+    wrapperPath,
+    cliPath,
+    identityPath: input.identityPath,
+    signerPath: input.signerPath
+  });
+  await writeRuntimeSidecar({
+    path: path.join(input.credentialDirectory, "mcp-runtime.json"),
+    wrapperPath,
+    runtimeDirectory,
+    npmCacheDirectory,
+    cliPath
+  });
+  messages.push(`Prepared stable local Haven MCP wrapper: ${wrapperPath}`);
+  return {
+    command: wrapperPath,
+    args: [],
+    wrapperPath,
+    runtimeDirectory,
+    npmCacheDirectory,
+    cliPath,
+    messages
+  };
 }
-function normalizeRuntime(runtime, env = process.env) {
-  const explicit = normalizeRuntimeName(runtime);
-  if (explicit) return explicit;
-  return detectRuntime(env) ?? "other";
+function assertSupportedNodeVersion(nodeVersion = process.versions.node, minimumNodeVersion = MCP_RUNTIME_MANIFEST.minimumNodeVersion) {
+  if (compareNodeVersions(nodeVersion, minimumNodeVersion) < 0) {
+    throw new UnsupportedNodeVersionError(nodeVersion, minimumNodeVersion);
+  }
 }
-function restartRequiredForRuntime(runtime, env = process.env) {
-  const mode = runtimeProfile(runtime, env).restartMode;
-  return mode === "restart-session" || mode === "restart-app";
+function compareNodeVersions(left, right) {
+  const leftParts = parseNodeVersion(left);
+  const rightParts = parseNodeVersion(right);
+  for (let i = 0; i < 3; i += 1) {
+    if (leftParts[i] !== rightParts[i]) return leftParts[i] > rightParts[i] ? 1 : -1;
+  }
+  return 0;
 }
-function normalizeRuntimeName(runtime) {
-  const key = runtime?.trim().toLowerCase();
-  if (!key) return null;
-  return RUNTIME_ALIASES[key.replace(/\s+/g, "-")] ?? null;
+function parseNodeVersion(value) {
+  const match = value.trim().match(/^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  if (!match) return [0, 0, 0];
+  return [
+    Number(match[1] ?? 0),
+    Number(match[2] ?? 0),
+    Number(match[3] ?? 0)
+  ];
+}
+async function installRuntimePackages(runtimeDirectory, npmCacheDirectory, runCommand) {
+  const args = [
+    "install",
+    "--prefix",
+    runtimeDirectory,
+    "--cache",
+    npmCacheDirectory,
+    "--no-audit",
+    "--no-fund",
+    "--omit=dev",
+    mcpPackageSpec(),
+    sdkPackageSpec()
+  ];
+  try {
+    if (runCommand) await runCommand("npm", args);
+    else await execFileAsync("npm", args, { timeout: 12e4, maxBuffer: 1024 * 1024 });
+  } catch (err) {
+    throw new Error(`Could not install local Haven MCP runtime ${mcpPackageSpec()}: ${err instanceof Error ? err.message : String(err)}`);
+  }
 }
-function detectRuntime(env) {
-  if (env.CLAUDECODE || env.CLAUDE_CODE || env.CLAUDECODE_CWD) return "claude-code";
-  if (env.CODEX_SANDBOX || env.CODEX_HOME || env.CODEX_CWD) return "codex-cli";
-  if (env.VSCODE_CWD || env.VSCODE_IPC_HOOK_CLI || env.TERM_PROGRAM === "vscode") return "vscode";
-  return null;
+async function installedRuntimeMatches(runtimeDirectory, cliPath) {
+  try {
+    await assertFileExists(cliPath, "local Haven MCP CLI");
+    const [mcpPackage, sdkPackage] = await Promise.all([
+      readPackageJson(path.join(runtimeDirectory, "node_modules", "@haven_ai", "mcp", "package.json")),
+      readPackageJson(path.join(runtimeDirectory, "node_modules", "@haven_ai", "sdk", "package.json"))
+    ]);
+    return mcpPackage.version === MCP_RUNTIME_MANIFEST.mcpVersion && sdkPackage.version === MCP_RUNTIME_MANIFEST.sdkVersion;
+  } catch {
+    return false;
+  }
+}
+async function readPackageJson(path) {
+  return JSON.parse(await promises.readFile(path, "utf8"));
+}
+async function writeWrapper(input) {
+  await promises.mkdir(path.dirname(input.wrapperPath), { recursive: true, mode: 448 });
+  await promises.chmod(path.dirname(input.wrapperPath), 448).catch(() => void 0);
+  const source = [
+    "#!/usr/bin/env node",
+    "import { spawn } from 'node:child_process'",
+    "",
+    `const cliPath = ${JSON.stringify(input.cliPath)}`,
+    `const identityPath = ${JSON.stringify(input.identityPath)}`,
+    `const signerPath = ${JSON.stringify(input.signerPath)}`,
+    "",
+    "const child = spawn(process.execPath, [cliPath, '--identity', identityPath, '--signer', signerPath, ...process.argv.slice(2)], {",
+    "  stdio: 'inherit',",
+    "})",
+    "",
+    "child.on('exit', (code, signal) => {",
+    "  if (signal) process.kill(process.pid, signal)",
+    "  else process.exit(code ?? 1)",
+    "})",
+    ""
+  ].join("\n");
+  await promises.writeFile(input.wrapperPath, source, { mode: 448 });
+  await promises.chmod(input.wrapperPath, 448).catch(() => void 0);
+}
+async function writeRuntimeSidecar(input) {
+  const value = {
+    mcp_package: MCP_RUNTIME_MANIFEST.mcpPackage,
+    mcp_version: MCP_RUNTIME_MANIFEST.mcpVersion,
+    sdk_package: MCP_RUNTIME_MANIFEST.sdkPackage,
+    sdk_version: MCP_RUNTIME_MANIFEST.sdkVersion,
+    minimum_node_version: MCP_RUNTIME_MANIFEST.minimumNodeVersion,
+    wrapper_path: input.wrapperPath,
+    runtime_directory: input.runtimeDirectory,
+    npm_cache_directory: input.npmCacheDirectory,
+    cli_path: input.cliPath
+  };
+  await promises.writeFile(input.path, `${JSON.stringify(value, null, 2)}
+`, { mode: 384 });
+  await promises.chmod(input.path, 384).catch(() => void 0);
+}
+async function assertFileExists(path, label) {
+  try {
+    await promises.access(path);
+  } catch {
+    throw new Error(`Missing ${label}: ${path}`);
+  }
 }
 async function acknowledgeLocalSignerConsent(signerPath, log) {
   try {
@@ -720,7 +1186,7 @@ function writeLogChunk2(log, chunk) {
 }
 
 // src/runtime-install.ts
-var execFileAsync = util.promisify(child_process.execFile);
+var execFileAsync2 = util.promisify(child_process.execFile);
 async function installRuntime(input, deps = {}) {
   const runtime = normalizeRuntime(input.runtime, deps.env);
   const profile = runtimeProfile(runtime, deps.env);
@@ -750,31 +1216,66 @@ async function installRuntime(input, deps = {}) {
       ]
     };
   }
-  const configResult = runtime === "claude-code" ? await configureClaudeCode(input, deps) : await writeRuntimeConfig({
+  let localRuntimeInstall;
+  let localRuntimeError;
+  if (localRuntime) {
+    try {
+      localRuntimeInstall = await prepareRuntimeForLocalMcp(input, deps);
+    } catch (err) {
+      localRuntimeError = err;
+    }
+  }
+  if (localRuntimeError) {
+    const errorCode2 = localRuntimePrepareErrorCode(localRuntimeError);
+    return {
+      runtime,
+      runtimeMcpMode: "local_stdio",
+      hostedMcpConfigured: false,
+      localSignerConfigured: false,
+      localMcpConfigured: false,
+      probeResult: errorCode2 === "local_mcp_unsupported_node_version" ? "local_stdio_mcp_unsupported_node_version" : "local_stdio_mcp_runtime_install_failed",
+      restartRequired: true,
+      nextUserAction: nextAction(runtime, profile.restartMode, errorCode2),
+      errorCode: errorCode2,
+      configTarget: profile.label,
+      signerAcknowledged: signerConsent?.acknowledged,
+      localMcpAcknowledged: localMcpConsent?.acknowledged,
+      activationCommand: void 0,
+      messages: [
+        ...consentMessages,
+        `Could not prepare local Haven MCP runtime: ${localRuntimeError instanceof Error ? localRuntimeError.message : String(localRuntimeError)}`
+      ]
+    };
+  }
+  const configResult = runtime === "claude-code" ? await configureClaudeCode(deps, localRuntimeInstall?.command ?? "") : await writeRuntimeConfig({
     runtime,
     hostedMcpUrl: input.hostedMcpUrl,
     apiKey: input.apiKey,
     identityPath: input.identityPath,
     signerPath: input.signerPath,
     credentialDirectory: input.credentialDirectory,
+    localMcpCommand: localRuntimeInstall?.command,
     homeDir: deps.homeDir
   });
-  const [hostedProbe, signerCredentialReady] = await Promise.all([
+  const localProbePromise = configResult.runtimeMcpMode === "local_stdio" && localRuntimeInstall ? runLocalMcpProbe(localRuntimeInstall, deps) : Promise.resolve(void 0);
+  const [hostedProbe, signerCredentialReady, localMcpProbe] = await Promise.all([
     configResult.hostedConfigured ? probeHostedMcpTools(input.apiKey, input.hostedMcpUrl, deps.fetch) : Promise.resolve({ status: "bad_response" }),
-    probeLocalSignerCredential(input.signerPath)
+    probeLocalSignerCredential(input.signerPath),
+    localProbePromise
   ]);
   const hostedOk = configResult.hostedConfigured && hostedProbe.status !== "unauthorized";
-  const localMcpOk = configResult.runtimeMcpMode === "local_stdio" && configResult.localMcpConfigured && signerCredentialReady && Boolean(localMcpConsent?.acknowledged);
+  const localMcpOk = configResult.runtimeMcpMode === "local_stdio" && configResult.localMcpConfigured && signerCredentialReady && Boolean(localMcpConsent?.acknowledged) && localMcpProbe?.status === "ok";
   const signerOk = configResult.runtimeMcpMode === "local_stdio" ? localMcpOk : configResult.signerConfigured && signerCredentialReady && Boolean(signerConsent?.acknowledged);
   const restartRequired = configResult.restartRequired || restartRequiredForRuntime(runtime, deps.env);
-  const errorCode = configResult.errorCode ?? (configResult.runtimeMcpMode === "local_stdio" ? localMcpConsentErrorCode(signerCredentialReady, localMcpConsent) : signerConsentErrorCode(signerCredentialReady, signerConsent));
+  const errorCode = configResult.errorCode ?? (configResult.runtimeMcpMode === "local_stdio" ? localMcpErrorCode(signerCredentialReady, localMcpConsent, localMcpProbe?.status) : signerConsentErrorCode(signerCredentialReady, signerConsent));
+  const localProbeMessages = localMcpProbe && localMcpProbe.status !== "ok" ? [`Local Haven MCP handshake failed: ${localMcpProbe.status}.`] : localMcpProbe?.status === "ok" ? ["Verified local Haven MCP tools with a stdio handshake."] : [];
   return {
     runtime,
     runtimeMcpMode: configResult.runtimeMcpMode,
     hostedMcpConfigured: hostedOk,
     localSignerConfigured: signerOk,
     localMcpConfigured: localMcpOk,
-    probeResult: buildProbeResult(configResult.runtimeMcpMode, configResult.hostedConfigured, hostedProbe.status, signerOk, localMcpOk),
+    probeResult: buildProbeResult(configResult.runtimeMcpMode, configResult.hostedConfigured, hostedProbe.status, signerOk, localMcpOk, localMcpProbe?.status),
     restartRequired,
     nextUserAction: nextAction(runtime, profile.restartMode, errorCode),
     errorCode,
@@ -782,7 +1283,7 @@ async function installRuntime(input, deps = {}) {
     signerAcknowledged: signerConsent?.acknowledged,
     localMcpAcknowledged: localMcpConsent?.acknowledged,
     activationCommand: configResult.activationCommand,
-    messages: [...consentMessages, ...configResult.messages]
+    messages: [...consentMessages, ...localRuntimeInstall?.messages ?? [], ...configResult.messages, ...localProbeMessages]
   };
 }
 function runtimeInstallCapabilities(runtime, env = process.env) {
@@ -792,23 +1293,21 @@ function runtimeInstallCapabilities(runtime, env = process.env) {
     restartRequired: restartRequiredForRuntime(runtime, env)
   };
 }
-async function configureClaudeCode(input, deps) {
+async function configureClaudeCode(deps, localMcpCommand) {
   const runCommand = deps.runCommand ?? defaultRunCommand;
+  const serverJson = JSON.stringify({
+    type: "stdio",
+    command: localMcpCommand,
+    args: [],
+    env: {}
+  });
   try {
-    await runCommand("claude", [
-      "mcp",
-      "add",
-      "haven",
-      "--",
-      "npx",
-      "-y",
-      localMcpPackageName2(),
-      "--identity",
-      input.identityPath,
-      "--signer",
-      input.signerPath
-    ]);
+    if (!localMcpCommand) throw new Error("local MCP wrapper command is required");
+    await runCommand("claude", ["mcp", "add-json", "haven", serverJson, "--scope", "user"]).catch(async () => {
+      await runCommand("claude", ["mcp", "add", "haven", "--scope", "user", "--", localMcpCommand]);
+    });
     await runCommand("claude", ["mcp", "remove", "haven-signer"]).catch(() => void 0);
+    const verified = await runCommand("claude", ["mcp", "get", "haven"]).then(() => true).catch(() => false);
     return {
       hostedConfigured: false,
       signerConfigured: true,
@@ -819,7 +1318,8 @@ async function configureClaudeCode(input, deps) {
       restartRequired: true,
       messages: [
         "Updated local Haven MCP entry with Claude Code.",
-        "After Haven approval, restart Claude Code normally so it can load Haven tools."
+        ...verified ? ["Verified Claude Code MCP entry."] : [],
+        "After Haven approval, Haven tools should appear in your next Claude Code message. If they don't, restart the session to load them."
       ]
     };
   } catch (err) {
@@ -840,11 +1340,12 @@ async function configureClaudeCode(input, deps) {
   }
 }
 async function defaultRunCommand(command, args) {
-  await execFileAsync(command, args, { timeout: 1e4 });
+  await execFileAsync2(command, args, { timeout: 1e4 });
 }
-function buildProbeResult(mode, hostedConfigured, hostedStatus, signerReady, localMcpReady) {
+function buildProbeResult(mode, hostedConfigured, hostedStatus, signerReady, localMcpReady, localMcpProbeStatus) {
   if (mode === "local_stdio") {
-    return localMcpReady ? "local_stdio_mcp_ready" : "local_stdio_mcp_unavailable";
+    if (localMcpReady) return "local_stdio_mcp_ready";
+    return localMcpProbeStatus ? `local_stdio_mcp_${localMcpProbeStatus}` : "local_stdio_mcp_unavailable";
   }
   const hostedPart = hostedConfigured ? `hosted_${hostedStatus}` : "hosted_not_configured";
   const signerPart = signerReady ? "local_signer_ready" : "local_signer_unavailable";
@@ -879,25 +1380,46 @@ function signerConsentErrorCode(signerCredentialReady, signerConsent) {
   if (!signerConsent?.acknowledged) return "local_signer_ack_required";
   return void 0;
 }
-function localMcpConsentErrorCode(signerCredentialReady, localMcpConsent) {
+function localMcpErrorCode(signerCredentialReady, localMcpConsent, localMcpProbeStatus) {
   if (!signerCredentialReady) return "local_signer_credential_unavailable";
   if (!localMcpConsent?.acknowledged) return "local_mcp_ack_required";
+  if (localMcpProbeStatus && localMcpProbeStatus !== "ok") return `local_mcp_probe_${localMcpProbeStatus}`;
   return void 0;
 }
 function nextAction(runtime, restartMode, errorCode) {
   if (errorCode) return "return_to_haven_for_wallet_approval_then_finish_runtime_setup";
   if (restartMode === "hot-reload") return "return_to_haven_for_wallet_approval";
-  if (runtime === "codex-cli") return "return_to_haven_for_wallet_approval_then_restart_codex";
+  if (runtime === "codex-cli" || runtime === "codex-desktop") return "return_to_haven_for_wallet_approval_then_restart_codex";
   if (runtime === "claude-code") return "return_to_haven_for_wallet_approval_then_restart_claude_code";
   if (restartMode === "restart-app") return "return_to_haven_for_wallet_approval_then_restart_app";
   if (restartMode === "restart-session") return "return_to_haven_for_wallet_approval_then_restart_agent_session";
   return "return_to_haven_for_wallet_approval_then_configure_runtime";
 }
-function localMcpPackageName2() {
-  return `@haven_ai/mcp@${mcp.MCP_VERSION}`;
-}
 function usesLocalMcp(runtime) {
-  return runtime === "codex-cli" || runtime === "claude-code";
+  return runtime === "codex-cli" || runtime === "codex-desktop" || runtime === "claude-code";
+}
+async function prepareRuntimeForLocalMcp(input, deps) {
+  const prepare = deps.prepareLocalMcpRuntime ?? ((runtimeInput) => prepareLocalMcpRuntime(runtimeInput, { runCommand: deps.runCommand }));
+  return prepare({
+    credentialDirectory: input.credentialDirectory,
+    identityPath: input.identityPath,
+    signerPath: input.signerPath,
+    homeDir: deps.homeDir
+  });
+}
+async function runLocalMcpProbe(runtimeInstall, deps) {
+  const probe = deps.probeLocalMcpTools ?? probeLocalMcpTools;
+  try {
+    return await probe(runtimeInstall.command, runtimeInstall.args, MCP_RUNTIME_MANIFEST.requiredTools);
+  } catch {
+    return { status: "process_error" };
+  }
+}
+function localRuntimePrepareErrorCode(err) {
+  if (err && typeof err === "object" && "code" in err && err.code === "local_mcp_unsupported_node_version") {
+    return "local_mcp_unsupported_node_version";
+  }
+  return "local_mcp_runtime_install_failed";
 }
 
 // src/runtime.ts
@@ -997,7 +1519,11 @@ async function runConnect(options, deps = {}) {
   }
   log("Return to Haven to approve the agent rules.");
   if (runtimeInstall.restartRequired) {
-    log("After approval, restart this agent normally so it can load Haven tools.");
+    if (runtimeRequiresHardRestart(runtimeInstall.runtime)) {
+      log("After approval, restart this agent so it can load Haven tools.");
+    } else {
+      log("After approval, Haven tools should appear in your next message. If they don't, restart this agent to load them.");
+    }
   }
   return {
     setupId: registration.setup_id,
@@ -1096,7 +1622,7 @@ function helpText() {
     "Options:",
     "  --setup <token>            Short-lived setup token from Haven.",
     "  --api <url>                Haven backend API URL. Defaults to HAVEN_API_URL or http://localhost:3001.",
-    "  --runtime <name>           Agent runtime hint, such as claude-code, codex-cli, cursor, vscode, or claude-desktop.",
+    "  --runtime <name>           Agent runtime hint, such as claude-code, codex-cli, codex-desktop, cursor, vscode, or claude-desktop.",
     "  --credentials-dir <path>   Credential directory fallback. Defaults to ~/.haven/agents.",
     "  --environment-label <text> Non-sensitive label shown in Haven setup review.",
     "  --ack-local-tools          Write the one-time local Haven tools acknowledgement during setup.",