@haven_ai/connect 0.1.21-alpha.0 → 0.1.23-alpha.0

package/dist/index.js

@@ -1,13 +1,15 @@
 import crypto from 'crypto';
 import { Wallet } from 'ethers';
-import { mkdir, rm, writeFile, access, chmod, readFile } from 'fs/promises';
+import { mkdir, rm, chmod, access, writeFile, readFile, unlink } from 'fs/promises';
 import { homedir, platform } from 'os';
 import { join, resolve, dirname } from 'path';
 import { execFile, spawn } from 'child_process';
 import { promisify } from 'util';
+import { parseDocument, isMap, stringify } from 'yaml';
 import { registeredToolNames, MCP_VERSION, ensureConsent, computeConsentHash, loadCredentials, consentInputFromClient } from '@haven_ai/mcp';
-import { HAVEN_MINIMUM_NODE_VERSION, SKILL_FOLDER_NAME, HAVEN_SKILL_MD, isSupportedNodeVersion, unsupportedNodeVersionMessage } from '@haven_ai/sdk';
+import { HAVEN_MINIMUM_NODE_VERSION, isSupportedNodeVersion, unsupportedNodeVersionMessage, SKILL_FOLDER_NAME, HAVEN_SKILL_MD } from '@haven_ai/sdk';
 import { ensureSignerConsent, computeSignerConsentHash, loadSignerCredentials, createEdgeSigner, toolSchemas } from '@haven_ai/signer';
+import { pathToFileURL } from 'url';
 
 // src/api.ts
 function createConnectApiClient(baseUrl, fetchImpl = fetch) {
@@ -173,11 +175,12 @@ async function writeCredentialFiles(input) {
       agentPath,
       {
         agent_id: input.agentId,
+        delegate_address: input.delegateAddress,
         safe_address: input.safeAddress,
         chain_id: input.chainId,
         network: input.network,
         agent_budget: input.agentBudget,
-        note: "Non-secret orientation for the agent: identity + configured budget. Contains no API key or signing key. For the live remaining budget, call haven_get_allowances."
+        note: "Non-secret orientation for the agent: public delegate/Haven wallet identity + configured budget. Contains no API key or signing key. For the live remaining budget, call haven_get_allowances."
       },
       input.warn
     );
@@ -229,9 +232,9 @@ var MCP_RUNTIME_MANIFEST = {
   mcpPackage: "@haven_ai/mcp",
   mcpVersion: MCP_VERSION,
   sdkPackage: "@haven_ai/sdk",
-  sdkVersion: "0.1.21-alpha.0",
+  sdkVersion: "0.1.23-alpha.0",
   signerPackage: "@haven_ai/signer",
-  signerVersion: "0.1.21-alpha.0",
+  signerVersion: "0.1.23-alpha.0",
   // Sourced from the SDK, never a literal (#1161). This field read '20.0.0'
   // while every package's `engines` said `>=24` and the docs said `>=24.0.0`,
   // so the guard that was supposed to enforce the floor waved Node v23 through
@@ -253,13 +256,20 @@ function signerPackageSpec() {
 }
 
 // src/config-writers.ts
+var HERMES_API_KEY_ENV = "MCP_HAVEN_API_KEY";
+var HermesConfigRecoveryError = class extends Error {
+  constructor() {
+    super("Hermes configuration recovery did not complete");
+    this.name = "HermesConfigRecoveryError";
+  }
+};
 var InvalidCodexTomlError = class extends Error {
   constructor(message) {
     super(message);
     this.name = "InvalidCodexTomlError";
   }
 };
-async function writeRuntimeConfig(input) {
+async function writeRuntimeConfig(input, deps = {}) {
   switch (input.runtime) {
     case "codex-cli":
     case "codex-desktop":
@@ -272,6 +282,8 @@ async function writeRuntimeConfig(input) {
       return writeJsonRuntimeConfig(input, vscodeInsidersConfigPath(input.homeDir), "servers");
     case "claude-desktop":
       return writeJsonRuntimeConfig(input, claudeDesktopConfigPath(input.homeDir), "mcpServers");
+    case "hermes":
+      return writeHermesConfig(input, deps);
     default:
       return {
         hostedConfigured: false,
@@ -325,6 +337,115 @@ function mergeJsonMcpConfig(existingJson, serverRoot, hostedServer, signerServer
   return `${JSON.stringify(config, null, 2)}
 `;
 }
+function mergeHermesYaml(existingYaml, hostedServer, signerServer) {
+  if (!existingYaml?.trim()) return renderHermesYaml({ haven: hostedServer, "haven-signer": signerServer });
+  const doc = parseDocument(existingYaml, { keepSourceTokens: true });
+  if (doc.errors.length > 0 || !isMap(doc.contents)) {
+    throw new Error("Hermes config must be a YAML object");
+  }
+  const mcpPair = doc.contents.items.find((item) => item.key?.toString() === "mcp_servers");
+  const existingServers = mcpPair && isMap(mcpPair.value) ? mcpPair.value.toJSON() : {};
+  const servers = isRecord(existingServers) ? existingServers : {};
+  const mergedServers = {
+    ...servers,
+    haven: hostedServer,
+    "haven-signer": signerServer
+  };
+  if (!mcpPair) {
+    return appendHermesMcpServers(existingYaml, mergedServers);
+  }
+  if (!mcpPair.value?.range) return replaceEmptyHermesMcpServers(existingYaml, mcpPair.key?.range, mergedServers);
+  return replaceHermesMcpServers(existingYaml, mcpPair.key?.range, mcpPair.value.range, mergedServers);
+}
+function mergeHermesEnv(existingEnv, apiKey) {
+  if (/[\r\n]/.test(apiKey)) throw new Error("Hermes API key must be a single line");
+  const assignment = `${HERMES_API_KEY_ENV}=${apiKey}`;
+  if (!existingEnv) return `${assignment}
+`;
+  const lineEnding = existingEnv.includes("\r\n") ? "\r\n" : "\n";
+  const hasTrailingNewline = /\r?\n$/.test(existingEnv);
+  const lines = existingEnv.split(/\r?\n/);
+  if (hasTrailingNewline) lines.pop();
+  let found = false;
+  const merged = lines.flatMap((line) => {
+    if (isHermesEnvAssignment(line)) {
+      if (found) return [];
+      found = true;
+      return [assignment];
+    }
+    if (isAmbiguousHermesEnvLine(line)) {
+      throw new Error("Hermes environment contains an ambiguous managed key");
+    }
+    return [line];
+  });
+  if (!found) {
+    return `${existingEnv}${hasTrailingNewline ? "" : lineEnding}${assignment}${lineEnding}`;
+  }
+  return `${merged.join(lineEnding)}${hasTrailingNewline ? lineEnding : ""}`;
+}
+function isHermesEnvAssignment(line) {
+  return /^\s*(?:export[ \t]+)?MCP_HAVEN_API_KEY[ \t]*=/.test(line);
+}
+function isAmbiguousHermesEnvLine(line) {
+  return /^\s*(?:export[ \t]+)?MCP_HAVEN_API_KEY\b/.test(line);
+}
+function appendHermesMcpServers(source, servers) {
+  const documentEnd = /(?:^|\n)[ \t]*\.\.\.[ \t]*(?:#[^\n]*)?\r?\n?$/.exec(source);
+  if (documentEnd) {
+    const markerStart = documentEnd.index + (documentEnd[0].startsWith("\n") ? 1 : 0);
+    const beforeMarker = source.slice(0, markerStart);
+    return `${beforeMarker}${beforeMarker.endsWith("\n") ? "" : "\n"}${renderHermesMcpServers(servers, "")}
+${source.slice(markerStart)}`;
+  }
+  const separator = source.endsWith("\n") ? "" : "\n";
+  return `${source}${separator}${renderHermesMcpServers(servers, "")}
+`;
+}
+function replaceHermesMcpServers(source, keyRange, valueRange, servers) {
+  const valueStart = valueRange[0];
+  const valueEnd = valueRange[1];
+  const valueLineStart = source.lastIndexOf("\n", valueStart - 1) + 1;
+  const keyStartsOnValueLine = keyRange?.[0] !== void 0 && keyRange[0] >= valueLineStart;
+  const nestedIndent = `${source.slice(valueLineStart, keyRange?.[0] ?? valueLineStart)}  `;
+  if (keyStartsOnValueLine) {
+    const keyStart = keyRange[0];
+    const keyEnd = keyRange[1];
+    const replacement2 = `${source.slice(keyStart, keyEnd)}:
+${renderHermesMcpServerEntries(servers, nestedIndent)}`;
+    const needsTrailingNewline2 = valueEnd < source.length && !source.slice(valueEnd).startsWith("\n");
+    return `${source.slice(0, keyStart)}${replacement2}${needsTrailingNewline2 ? "\n" : ""}${source.slice(valueEnd)}`;
+  }
+  const indent = source.slice(valueLineStart, valueStart);
+  const rendered = stringify(servers, { lineWidth: 120 }).trimEnd();
+  const replacement = rendered.split("\n").map((line, index) => index === 0 ? line : `${indent}${line}`).join("\n");
+  const needsTrailingNewline = valueEnd < source.length && !source.slice(valueEnd).startsWith("\n");
+  return `${source.slice(0, valueStart)}${replacement}${needsTrailingNewline ? "\n" : ""}${source.slice(valueEnd)}`;
+}
+function replaceEmptyHermesMcpServers(source, keyRange, servers) {
+  if (!keyRange) throw new Error("Hermes config mcp_servers key is invalid");
+  const keyStart = keyRange[0];
+  const keyEnd = keyRange[1];
+  const lineStart = source.lastIndexOf("\n", keyStart - 1) + 1;
+  const lineEnd = source.indexOf("\n", keyEnd);
+  const nestedIndent = `${source.slice(lineStart, keyStart)}  `;
+  const replacement = `${source.slice(keyStart, keyEnd)}:
+${renderHermesMcpServerEntries(servers, nestedIndent)}`;
+  return `${source.slice(0, keyStart)}${replacement}${lineEnd === -1 ? "\n" : source.slice(lineEnd)}`;
+}
+function renderHermesYaml(servers) {
+  return `${renderHermesMcpServers(servers, "")}
+`;
+}
+function renderHermesMcpServers(servers, indent) {
+  return `mcp_servers:
+${renderHermesMcpServerEntries(servers, `${indent}  `)}`;
+}
+function renderHermesMcpServerEntries(servers, indent) {
+  return stringify(servers, { lineWidth: 120 }).trimEnd().split("\n").map((line) => `${indent}${line}`).join("\n");
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
 function mergeCodexToml(existingToml, localMcpCommand) {
   let next = removeTomlTableTree(removeTomlTableTree(existingToml, "mcp_servers.haven"), "mcp_servers.haven_signer");
   next = next.trimEnd();
@@ -395,6 +516,82 @@ async function writeJsonRuntimeConfig(input, target, serverRoot) {
     };
   }
 }
+async function writeHermesConfig(input, deps) {
+  const target = hermesConfigPath(input.homeDir);
+  const envTarget = hermesEnvPath(input.homeDir);
+  try {
+    const [existing, existingEnv] = await Promise.all([readOptional(target), readOptional(envTarget)]);
+    const hostedServer = {
+      ...buildHostedServer(input.hostedMcpUrl, `\${${HERMES_API_KEY_ENV}}`, input.runtime),
+      enabled: true
+    };
+    const signerServer = {
+      ...buildSignerServer(resolveSignerLaunchSpec(input), input.runtime),
+      enabled: true
+    };
+    const merged = mergeHermesYaml(
+      existing,
+      hostedServer,
+      signerServer
+    );
+    const mergedEnv = mergeHermesEnv(existingEnv, input.apiKey);
+    const writeText = deps.writeOwnerOnlyText ?? writeOwnerOnlyText;
+    await writeText(envTarget, mergedEnv);
+    try {
+      await writeText(target, merged);
+    } catch (err) {
+      const recovered = await restoreHermesFiles(target, existing, envTarget, existingEnv, writeText);
+      if (!recovered) throw new HermesConfigRecoveryError();
+      throw err;
+    }
+    return {
+      hostedConfigured: true,
+      signerConfigured: true,
+      localMcpConfigured: false,
+      runtimeMcpMode: "hosted_plus_signer",
+      target: "Hermes Agent config",
+      changed: existing !== merged || existingEnv !== mergedEnv,
+      restartRequired: true,
+      messages: [
+        `Updated Haven MCP entries in ${target}; stored the hosted MCP identity in ${envTarget}.`,
+        "Restart Hermes (start a new session; gateway users: /restart), then verify with `hermes mcp list`, `hermes mcp test haven`, and `hermes mcp test haven-signer`.",
+        "If no mcp_* tools appear after restart, ensure the MCP SDK is installed in Hermes: pip install mcp"
+      ]
+    };
+  } catch (err) {
+    const recoveryIncomplete = err instanceof HermesConfigRecoveryError;
+    return {
+      hostedConfigured: false,
+      signerConfigured: false,
+      localMcpConfigured: false,
+      runtimeMcpMode: "hosted_plus_signer",
+      target: "Hermes Agent config",
+      changed: false,
+      restartRequired: true,
+      messages: [recoveryIncomplete ? "Could not update Hermes Agent config. Recovery did not complete; inspect the Hermes configuration before retrying." : "Could not update Hermes Agent config. Existing configuration was left unchanged."],
+      errorCode: "runtime_config_write_failed"
+    };
+  }
+}
+async function restoreHermesFiles(configPath, existingConfig, envPath, existingEnv, writeText) {
+  const [envResult, configResult] = await Promise.allSettled([
+    restoreOptionalText(envPath, existingEnv, writeText),
+    restoreOptionalText(configPath, existingConfig, writeText)
+  ]);
+  return envResult.status === "fulfilled" && configResult.status === "fulfilled";
+}
+async function restoreOptionalText(path, existing, writeText) {
+  if (existing !== null) {
+    await writeText(path, existing);
+    return;
+  }
+  try {
+    await unlink(path);
+  } catch (err) {
+    if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") return;
+    throw err;
+  }
+}
 async function writeCodexConfig(input) {
   const target = codexConfigPath(input.homeDir);
   const local = input.mode === "local";
@@ -685,6 +882,15 @@ function claudeDesktopConfigPath(homeDir = homedir()) {
   }
   return resolve(homeDir, ".config", "Claude", "claude_desktop_config.json");
 }
+function hermesConfigPath(homeDir) {
+  return join(hermesHomePath(homeDir), "config.yaml");
+}
+function hermesEnvPath(homeDir) {
+  return join(hermesHomePath(homeDir), ".env");
+}
+function hermesHomePath(homeDir) {
+  return process.env.HERMES_HOME ?? join(homeDir ?? homedir(), ".hermes");
+}
 function configTargetLabel(runtime) {
   switch (runtime) {
     case "codex-cli":
@@ -1190,49 +1396,64 @@ var RUNTIME_PROFILES = {
     id: "claude-code",
     label: "Claude Code",
     restartMode: "restart-session",
-    canWriteRuntimeConfig: true
+    canWriteRuntimeConfig: true,
+    activationInstruction: "Start a new Claude Code session so it loads the Haven MCP entries."
   },
   "codex-cli": {
     id: "codex-cli",
     label: "Codex CLI",
     restartMode: "restart-session",
-    canWriteRuntimeConfig: true
+    canWriteRuntimeConfig: true,
+    activationInstruction: "Start a fresh Codex CLI session (for example, run `codex resume --last`)."
   },
   "codex-desktop": {
     id: "codex-desktop",
     label: "Codex Desktop",
     restartMode: "restart-session",
-    canWriteRuntimeConfig: true
+    canWriteRuntimeConfig: true,
+    activationInstruction: "Quit and reopen Codex Desktop so it loads the Haven MCP entries."
   },
   cursor: {
     id: "cursor",
     label: "Cursor",
     restartMode: "hot-reload",
-    canWriteRuntimeConfig: true
+    canWriteRuntimeConfig: true,
+    activationInstruction: "Wait for Cursor to hot-reload the Haven MCP entries; no app restart is required."
   },
   vscode: {
     id: "vscode",
     label: "VS Code",
     restartMode: "hot-reload",
-    canWriteRuntimeConfig: true
+    canWriteRuntimeConfig: true,
+    activationInstruction: "Wait for VS Code to hot-reload the Haven MCP entries; no app restart is required."
   },
   "vscode-insiders": {
     id: "vscode-insiders",
     label: "VS Code Insiders",
     restartMode: "hot-reload",
-    canWriteRuntimeConfig: true
+    canWriteRuntimeConfig: true,
+    activationInstruction: "Wait for VS Code Insiders to hot-reload the Haven MCP entries; no app restart is required."
   },
   "claude-desktop": {
     id: "claude-desktop",
     label: "Claude Desktop",
     restartMode: "restart-app",
-    canWriteRuntimeConfig: true
+    canWriteRuntimeConfig: true,
+    activationInstruction: "Quit and reopen Claude Desktop so it loads the Haven MCP entries."
+  },
+  hermes: {
+    id: "hermes",
+    label: "Hermes Agent",
+    restartMode: "restart-session",
+    canWriteRuntimeConfig: true,
+    activationInstruction: "Start a new Hermes session; in Hermes Gateway, run `/restart` instead."
   },
   other: {
     id: "other",
     label: "Other agent runtime",
     restartMode: "manual",
-    canWriteRuntimeConfig: false
+    canWriteRuntimeConfig: false,
+    activationInstruction: "Finish the manual MCP setup shown above, then start a fresh session in that runtime."
   }
 };
 var RUNTIME_ALIASES = {
@@ -1265,6 +1486,10 @@ var RUNTIME_ALIASES = {
   "claude_desktop": "claude-desktop",
   claudesktop: "claude-desktop",
   desktop: "claude-desktop",
+  hermes: "hermes",
+  "hermes-agent": "hermes",
+  hermes_agent: "hermes",
+  hermesagent: "hermes",
   other: "other",
   manual: "other"
 };
@@ -1280,8 +1505,9 @@ 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 runtimeVerificationInstruction(runtime) {
+  const label = RUNTIME_PROFILES[runtime].label;
+  return `In ${label}, run the read-only \`haven_get_agent\` and \`haven_get_allowances\` tools to confirm the Haven wallet and live budget. Do not sign, fund, or create a payment to verify setup.`;
 }
 function normalizeRuntimeName(runtime) {
   const key = runtime?.trim().toLowerCase();
@@ -1292,6 +1518,7 @@ 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";
+  if (env.HERMES_HOME || env.HERMES_AGENT) return "hermes";
   return null;
 }
 async function acknowledgeLocalSignerConsent(signerPath, log) {
@@ -1466,11 +1693,12 @@ async function installRuntime(input, deps = {}) {
     probeLocalSignerCredential(input.signerPath),
     localProbePromise
   ]);
-  const hostedOk = configResult.hostedConfigured && hostedProbe.status !== "unauthorized";
+  const hostedOk = configResult.hostedConfigured && hostedProbe.status === "ok";
   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" ? localMcpErrorCode(signerCredentialReady, localMcpConsent, localMcpProbe?.status) : signerConsentErrorCode(signerCredentialReady, signerConsent));
+  const errorCode = configResult.errorCode ?? (configResult.runtimeMcpMode === "local_stdio" ? localMcpErrorCode(signerCredentialReady, localMcpConsent, localMcpProbe?.status) : hostedMcpErrorCode(configResult.hostedConfigured, hostedProbe.status) ?? signerConsentErrorCode(signerCredentialReady, signerConsent));
+  const hostedProbeMessages = configResult.hostedConfigured && hostedProbe.status !== "ok" ? [`Hosted Haven MCP probe failed: ${hostedProbe.status}.`] : configResult.hostedConfigured ? ["Verified hosted Haven MCP tools with a read-only handshake."] : [];
   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."] : [];
   const skillInstall = runtime === "claude-code" && !configResult.errorCode ? await installClaudeSkill(deps.homeDir) : void 0;
   return {
@@ -1489,7 +1717,7 @@ async function installRuntime(input, deps = {}) {
     activationCommand: configResult.activationCommand,
     skillInstalled: skillInstall?.installed,
     signerRuntimePrepared,
-    messages: [...consentMessages, ...localRuntimeInstall?.messages ?? [], ...configResult.messages, ...localProbeMessages, ...skillInstall?.messages ?? []]
+    messages: [...consentMessages, ...localRuntimeInstall?.messages ?? [], ...configResult.messages, ...hostedProbeMessages, ...localProbeMessages, ...skillInstall?.messages ?? []]
   };
 }
 function runtimeInstallCapabilities(runtime, env = process.env) {
@@ -1650,6 +1878,10 @@ function signerConsentErrorCode(signerCredentialReady, signerConsent) {
   if (!signerConsent?.acknowledged) return "local_signer_ack_required";
   return void 0;
 }
+function hostedMcpErrorCode(hostedConfigured, hostedProbeStatus) {
+  if (!hostedConfigured || hostedProbeStatus === "ok") return void 0;
+  return `hosted_mcp_probe_${hostedProbeStatus}`;
+}
 function localMcpErrorCode(signerCredentialReady, localMcpConsent, localMcpProbeStatus) {
   if (!signerCredentialReady) return "local_signer_credential_unavailable";
   if (!localMcpConsent?.acknowledged) return "local_mcp_ack_required";
@@ -1701,13 +1933,17 @@ function localRuntimePrepareErrorCode(err) {
 }
 
 // src/runtime.ts
-var CONNECTOR_VERSION = "0.1.21-alpha.0";
+var CONNECTOR_VERSION = "0.1.23-alpha.0";
+var CONNECT_OUTCOME_SCHEMA_VERSION = 1;
 async function runConnect(options, deps = {}) {
   assertSupportedNodeVersion(deps.nodeVersion, MCP_RUNTIME_MANIFEST.minimumNodeVersion);
   const connectorVersion = options.connectorVersion ?? CONNECTOR_VERSION;
   const api = deps.api ?? createConnectApiClient(options.apiBaseUrl);
-  const log = secureLogger(deps.log ?? ((message) => process.stdout.write(`${message}
-`)));
+  const log = secureLogger(
+    deps.log ?? ((message) => process.stdout.write(`${message}
+`)),
+    deps.redactPaths === true
+  );
   const writeCredentials = deps.writeCredentials ?? writeCredentialFiles;
   const preflightStorage = deps.preflightStorage ?? preflightCredentialStorage;
   const runRuntimeInstall = deps.installRuntime ?? installRuntime;
@@ -1728,6 +1964,7 @@ async function runConnect(options, deps = {}) {
     connectorVersion,
     runtime: options.runtime
   });
+  assertSetupChallengeIsUsable(setup.challenge.expires_at);
   printSetupSummary(setup, log);
   await preflightStorage({ baseDir: options.credentialsDir, warn: log });
   log("Checked local credential storage \u2014 all clear.");
@@ -1736,21 +1973,31 @@ async function runConnect(options, deps = {}) {
   log("Minting a fresh signing key and API key \u2014 both stay on this machine.");
   const proofSignature = await localKey.signChallenge(setup.challenge.message);
   log("Introducing your agent to Haven\u2026");
-  const registration = await api.registerSetup({
-    setupToken: options.setupToken,
-    connectorVersion,
-    runtime: options.runtime,
-    challengeId: setup.challenge.id,
-    delegateAddress: localKey.address,
-    proofSignature,
-    apiKeyHash: hashAgentApiKey(localApiKey),
-    apiKeyPrefix: agentApiKeyPrefix(localApiKey),
-    connectorContext: {
-      environment_label: options.environmentLabel ?? "Local workspace",
-      config_target: installCapabilities.canWriteRuntimeConfig ? "agent runtime MCP config" : "local credential files"
-    },
-    installCapabilities
-  });
+  let registration;
+  try {
+    registration = await api.registerSetup({
+      setupToken: options.setupToken,
+      connectorVersion,
+      runtime: options.runtime,
+      challengeId: setup.challenge.id,
+      delegateAddress: localKey.address,
+      proofSignature,
+      apiKeyHash: hashAgentApiKey(localApiKey),
+      apiKeyPrefix: agentApiKeyPrefix(localApiKey),
+      connectorContext: {
+        environment_label: options.environmentLabel ?? "Local workspace",
+        config_target: installCapabilities.canWriteRuntimeConfig ? "agent runtime MCP config" : "local credential files"
+      },
+      installCapabilities
+    });
+  } catch (err) {
+    if (isExpiredSetupChallenge(err)) {
+      throw new Error(
+        "The Haven setup challenge expired while connecting. Return to Haven, start a fresh connection, and run its new Connect command. Do not reuse or paste credentials."
+      );
+    }
+    throw err;
+  }
   log(`Registered signing address with Haven: ${shortAddress(registration.delegate_address)}.`);
   log("Tucking your credentials away safely on disk\u2026");
   const credentialPaths = await writeCredentials({
@@ -1827,7 +2074,69 @@ async function runConnect(options, deps = {}) {
     setupId: registration.setup_id,
     agentId: registration.agent_id,
     delegateAddress: registration.delegate_address,
-    credentialPaths
+    credentialPaths,
+    outcome: completionOutcome({
+      runtimeInstall,
+      delegateAddress: registration.delegate_address,
+      setupChallengeExpiresAt: setup.challenge.expires_at,
+      approvalRequired: registration.agent_status === "pending_approval"
+    })
+  };
+}
+function completionOutcome(input) {
+  const { runtimeInstall } = input;
+  const manualSetup = runtimeInstall.errorCode === "manual_runtime_setup_required";
+  const nextAction2 = runtimeInstall.nextUserAction;
+  const outcome = {
+    schema_version: CONNECT_OUTCOME_SCHEMA_VERSION,
+    outcome: runtimeInstall.errorCode ? "action_required" : "complete",
+    runtime: runtimeInstall.runtime,
+    topology: runtimeInstall.runtimeMcpMode,
+    configuration: {
+      hosted_mcp: runtimeInstall.hostedMcpConfigured,
+      local_signer: runtimeInstall.localSignerConfigured,
+      local_mcp: runtimeInstall.localMcpConfigured
+    },
+    probe: { result: runtimeInstall.probeResult },
+    activation: {
+      restart_required: runtimeInstall.restartRequired,
+      instruction: manualSetup ? "Finish the manual MCP setup using the secret-free references shown in normal Connect output, then start a fresh session." : runtimeProfile(runtimeInstall.runtime).activationInstruction
+    },
+    next_action: nextAction2,
+    approval: { required: input.approvalRequired, expires_at: null },
+    verification: {
+      tools: ["haven_get_agent", "haven_get_allowances"],
+      instruction: runtimeVerificationInstruction(runtimeInstall.runtime)
+    },
+    // The backend contract supplies a 20-byte address. If an unexpected
+    // malformed value arrives, do not echo it into an automation-facing
+    // record; the human log has already been redacted separately.
+    delegate_address: /^0x[0-9a-fA-F]{40}$/.test(input.delegateAddress) ? shortAddress(input.delegateAddress) : "[delegate-address-redacted]",
+    ...input.setupChallengeExpiresAt ? { setup_challenge_expires_at: input.setupChallengeExpiresAt } : {},
+    ...runtimeInstall.errorCode ? { error: { code: runtimeInstall.errorCode, next_action: nextAction2 } } : {}
+  };
+  return outcome;
+}
+function failedConnectOutcome(runtimeHint, error) {
+  const message = error instanceof Error ? error.message : "";
+  const code = /Node\.js >=/i.test(message) ? "unsupported_node_version" : /setup challenge.*expired|expired or invalid/i.test(message) ? "setup_challenge_expired_or_invalid" : /only available for Claude Code and Codex/i.test(message) ? "local_mcp_unsupported_runtime" : "connect_failed";
+  const runtime = normalizeRuntime(runtimeHint);
+  const nextAction2 = code === "setup_challenge_expired_or_invalid" ? "return_to_haven_for_fresh_setup" : code === "unsupported_node_version" ? "install_supported_node_and_rerun_connect" : code === "local_mcp_unsupported_runtime" ? "rerun_without_local_mcp" : "review_the_safe_error_output_and_start_a_fresh_haven_setup_if_needed";
+  return {
+    schema_version: CONNECT_OUTCOME_SCHEMA_VERSION,
+    outcome: "failed",
+    runtime,
+    topology: "unknown",
+    configuration: { hosted_mcp: false, local_signer: false, local_mcp: false },
+    probe: { result: "not_run" },
+    activation: { restart_required: false, instruction: "Resolve the reported problem before activating Haven tools." },
+    next_action: nextAction2,
+    approval: { required: false, expires_at: null },
+    verification: {
+      tools: ["haven_get_agent", "haven_get_allowances"],
+      instruction: "After a successful setup and activation, verify only with haven_get_agent and haven_get_allowances."
+    },
+    error: { code, next_action: nextAction2 }
   };
 }
 function printSetupSummary(setup, log) {
@@ -1840,10 +2149,26 @@ function printSetupSummary(setup, log) {
       );
     }
   }
-  log(`Setup challenge expires at ${setup.challenge.expires_at}.`);
+  log(`Setup challenge expires at ${setup.challenge.expires_at}. If it expires, return to Haven for a fresh setup and rerun Connect \u2014 do not reuse or paste credentials.`);
+}
+function assertSetupChallengeIsUsable(expiresAt) {
+  const expiresAtMs = Date.parse(expiresAt);
+  if (!Number.isNaN(expiresAtMs) && expiresAtMs > Date.now()) return;
+  throw new Error(
+    "This Haven setup challenge is expired or invalid. Return to Haven, start a fresh connection, and rerun Connect. No local credentials were written."
+  );
 }
-function secureLogger(log) {
-  return (message) => log(redactSecrets(message));
+function isExpiredSetupChallenge(err) {
+  return err instanceof Error && /(?:setup )?challenge.*expir|expir.*(?:setup )?challenge/i.test(err.message);
+}
+function secureLogger(log, redactPaths = false) {
+  return (message) => {
+    let safe = redactSecrets(message);
+    if (redactPaths) {
+      safe = safe.replace(/(?:~|\/)[^\s`"']*\/(?:identity|signer|agent)\.json\b/g, "[credential-file-redacted]").replace(/(?:~|\/)[^\s`"']*\/\.env\b/g, "[credential-env-redacted]");
+    }
+    log(safe);
+  };
 }
 function printRuntimeInstall(result, log) {
   for (const message of result.messages) log(message);
@@ -1860,17 +2185,30 @@ function printRuntimeInstall(result, log) {
     log("Local Haven signer still needs runtime setup.");
   }
 }
-function printNextSteps(result, log) {
-  log("Next: approve the agent rules in Haven. No Haven tools appear until you approve \u2014 restart or not.");
-  if (result.restartRequired) {
-    if (runtimeRequiresHardRestart(result.runtime)) {
-      log("After you approve, restart this agent so it can load Haven tools.");
-    } else {
-      log("After you approve, restart this agent \u2014 your current session won't load the Haven tools until you do.");
-    }
-  } else {
-    log("After you approve, the Haven tools should appear in this runtime shortly.");
+function completionHandoffLines(result) {
+  if (result.errorCode === "manual_runtime_setup_required") {
+    return [
+      "Next steps:",
+      "1. Return to Haven and approve the agent rules. Approval \u2014 not restarting \u2014 unlocks Haven tools.",
+      "2. Finish the manual MCP setup using the secret-free file references printed above, then start a fresh session in your runtime.",
+      `3. ${runtimeVerificationInstruction(result.runtime)}`
+    ];
+  }
+  if (result.errorCode) {
+    return [
+      "Recovery: runtime setup is not complete. Resolve the reported problem, then return to Haven for a fresh connection and run its new Connect command. Do not manually edit runtime config or paste credentials into prompts, logs, or config."
+    ];
   }
+  const profile = runtimeProfile(result.runtime);
+  return [
+    "Next steps:",
+    "1. Return to Haven and approve the agent rules. Approval \u2014 not restarting \u2014 unlocks Haven tools.",
+    `2. ${profile.activationInstruction}`,
+    `3. ${runtimeVerificationInstruction(result.runtime)}`
+  ];
+}
+function printNextSteps(result, log) {
+  for (const line of completionHandoffLines(result)) log(line);
 }
 
 // src/args.ts
@@ -1880,10 +2218,13 @@ function parseArgs(argv, env = process.env) {
     connectorVersion: CONNECTOR_VERSION
   };
   let help = false;
+  let json = false;
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === "--help" || arg === "-h") {
       help = true;
+    } else if (arg === "--json") {
+      json = true;
     } else if (arg === "--setup" || arg === "--setup-token") {
       options.setupToken = requireValue(argv, ++i, arg);
     } else if (arg === "--api" || arg === "--api-url") {
@@ -1910,7 +2251,7 @@ function parseArgs(argv, env = process.env) {
     }
   }
   if (help) {
-    return { options, help };
+    return { options, help, json };
   }
   if (!options.setupToken) {
     throw new Error("Missing --setup <hv_setup_...> setup token.");
@@ -1919,7 +2260,7 @@ function parseArgs(argv, env = process.env) {
     throw new Error("Missing --api <Haven API URL>.");
   }
   options.apiBaseUrl = options.apiBaseUrl.replace(/\/+$/, "");
-  return { options, help };
+  return { options, help, json };
 }
 function helpText() {
   return [
@@ -1934,16 +2275,17 @@ 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, codex-desktop, cursor, vscode, or claude-desktop.",
+    "  --runtime <name>           Agent runtime hint, such as claude-code, codex-cli, codex-desktop, cursor, vscode, claude-desktop, or hermes.",
     "  --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.",
     "  --ack-signer               Backward-compatible alias for --ack-local-tools.",
     "  --local                    Advanced: install the fully-local Haven MCP (no hosted dependency).",
     "                             Only available for Claude Code and Codex. Default is hosted MCP + local signer.",
+    "  --json                     Emit one versioned, secret-free result object on stdout; progress stays on stderr.",
     "  --help                     Show this help.",
     "",
-    "The connector never prints the private key and never sends it to Haven."
+    "The connector never prints the private key and never sends it to Haven. JSON output never includes credential contents or full credential paths."
   ].join("\n");
 }
 function requireValue(argv, index, option) {
@@ -1953,7 +2295,55 @@ function requireValue(argv, index, option) {
   }
   return value;
 }
+async function runCli(argv, io = {
+  stdout: (message) => process.stdout.write(message),
+  stderr: (message) => process.stderr.write(message)
+}) {
+  const wantsJson = argv.includes("--json");
+  let parsed;
+  try {
+    parsed = parseArgs(argv);
+  } catch (err) {
+    if (wantsJson) {
+      io.stdout(`${JSON.stringify(failedConnectOutcome(void 0, err))}
+`);
+    } else {
+      io.stderr(`${redactSecrets(err instanceof Error ? err.message : String(err))}
+`);
+    }
+    return 1;
+  }
+  if (parsed.help) {
+    io.stdout(`${helpText()}
+`);
+    return 0;
+  }
+  try {
+    const result = await runConnect(parsed.options, {
+      log: (message) => (parsed.json ? io.stderr : io.stdout)(`${message}
+`),
+      redactPaths: parsed.json
+    });
+    if (parsed.json) io.stdout(`${JSON.stringify(result.outcome)}
+`);
+    return 0;
+  } catch (err) {
+    if (parsed.json) {
+      io.stdout(`${JSON.stringify(failedConnectOutcome(parsed.options.runtime, err))}
+`);
+    } else {
+      io.stderr(`${redactSecrets(err instanceof Error ? err.message : String(err))}
+`);
+    }
+    return 1;
+  }
+}
+async function main() {
+  const exitCode = await runCli(process.argv.slice(2));
+  if (exitCode !== 0) process.exitCode = exitCode;
+}
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) void main();
 
-export { CONNECTOR_VERSION, MCP_RUNTIME_MANIFEST, createConnectApiClient, defaultAgentDirectory, delegateKeyFromPrivateKey, generateDelegateKey, helpText, installRuntime, mcpPackageSpec, normalizeRuntime, parseArgs, prepareSignerRuntime, redactSecrets, runConnect, runtimeInstallCapabilities, runtimeProfile, sdkPackageSpec, shortAddress, signerPackageSpec, writeCredentialFiles };
+export { CONNECTOR_VERSION, CONNECT_OUTCOME_SCHEMA_VERSION, MCP_RUNTIME_MANIFEST, completionOutcome, createConnectApiClient, defaultAgentDirectory, delegateKeyFromPrivateKey, failedConnectOutcome, generateDelegateKey, helpText, installRuntime, mcpPackageSpec, normalizeRuntime, parseArgs, prepareSignerRuntime, redactSecrets, runCli, runConnect, runtimeInstallCapabilities, runtimeProfile, sdkPackageSpec, shortAddress, signerPackageSpec, writeCredentialFiles };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map