@haven_ai/connect 0.1.22-alpha.0 → 0.1.23-alpha.1

package/dist/index.js

@@ -1,14 +1,16 @@
+import { HAVEN_MINIMUM_NODE_VERSION, isSupportedNodeVersion, unsupportedNodeVersionMessage, SKILL_FOLDER_NAME, HAVEN_SKILL_MD, resolveTokenFromAddress } from '@haven_ai/sdk';
 import crypto from 'crypto';
 import { Wallet } from 'ethers';
-import { mkdir, rm, writeFile, access, chmod, readFile, unlink } 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 { ensureSignerConsent, computeSignerConsentHash, loadSignerCredentials, createEdgeSigner, toolSchemas } from '@haven_ai/signer';
+import { realpathSync } from 'fs';
+import { fileURLToPath, pathToFileURL } from 'url';
 
 // src/api.ts
 function createConnectApiClient(baseUrl, fetchImpl = fetch) {
@@ -40,6 +42,10 @@ function createConnectApiClient(baseUrl, fetchImpl = fetch) {
         }
       })
     }),
+    getConnectorStatus: (setupId, apiKey) => request(fetchImpl, `${root}/agent-connection-setups/${encodeURIComponent(setupId)}/connector-status`, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${apiKey}` }
+    }),
     updateInstallStatus: async (setupId, apiKey, input) => {
       await request(fetchImpl, `${root}/agent-connection-setups/${encodeURIComponent(setupId)}/install-status`, {
         method: "POST",
@@ -66,6 +72,14 @@ function createConnectApiClient(baseUrl, fetchImpl = fetch) {
     }
   };
 }
+var ConnectRequestError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "ConnectRequestError";
+  }
+  status;
+};
 async function request(fetchImpl, url, init) {
   const response = await fetchImpl(url, {
     ...init,
@@ -78,7 +92,7 @@ async function request(fetchImpl, url, init) {
   const body = text ? JSON.parse(text) : null;
   if (!response.ok) {
     const message = body?.error ?? body?.message ?? `${response.status} ${response.statusText}`;
-    throw new Error(`Haven setup request failed: ${message}`);
+    throw new ConnectRequestError(`Haven setup request failed: ${message}`, response.status);
   }
   return body;
 }
@@ -174,11 +188,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
     );
@@ -230,9 +245,9 @@ var MCP_RUNTIME_MANIFEST = {
   mcpPackage: "@haven_ai/mcp",
   mcpVersion: MCP_VERSION,
   sdkPackage: "@haven_ai/sdk",
-  sdkVersion: "0.1.22-alpha.0",
+  sdkVersion: "0.1.23-alpha.1",
   signerPackage: "@haven_ai/signer",
-  signerVersion: "0.1.22-alpha.0",
+  signerVersion: "0.1.23-alpha.1",
   // 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
@@ -1394,55 +1409,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
+    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 = {
@@ -1494,8 +1518,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();
@@ -1681,11 +1706,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 {
@@ -1704,7 +1730,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) {
@@ -1865,6 +1891,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";
@@ -1916,13 +1946,17 @@ function localRuntimePrepareErrorCode(err) {
 }
 
 // src/runtime.ts
-var CONNECTOR_VERSION = "0.1.22-alpha.0";
+var CONNECTOR_VERSION = "0.1.23-alpha.1";
+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;
@@ -1943,6 +1977,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.");
@@ -1951,21 +1986,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({
@@ -2015,6 +2060,9 @@ async function runConnect(options, deps = {}) {
   } else {
     log("Haven setup on this machine is complete.");
   }
+  if (options.waitForApproval !== false && !runtimeInstall.errorCode) {
+    await waitForBudgetApproval(api, registration.setup_id, localApiKey, log, options.approvalWait);
+  }
   printNextSteps(runtimeInstall, log);
   try {
     await api.updateInstallStatus(registration.setup_id, localApiKey, {
@@ -2042,7 +2090,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) {
@@ -2055,10 +2165,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);
@@ -2075,17 +2201,85 @@ 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.");
+function formatAtomicAmount(atomic, decimals) {
+  const s = atomic.toString().padStart(decimals + 1, "0");
+  const intPart = s.slice(0, s.length - decimals) || "0";
+  const fracPart = s.slice(s.length - decimals).replace(/0+$/, "");
+  return fracPart ? `${intPart}.${fracPart}` : intPart;
+}
+function describeResetPeriod(resetPeriodMin) {
+  if (resetPeriodMin === 1440) return "per day";
+  if (resetPeriodMin === 60) return "per hour";
+  if (resetPeriodMin === 0) return "with no automatic reset";
+  return `per ${resetPeriodMin} minutes`;
+}
+function describeApprovedBudget(budget) {
+  const token = resolveTokenFromAddress(budget.token_address);
+  const amount = token ? `${formatAtomicAmount(BigInt(budget.amount), token.decimals)} ${budget.token_symbol}` : `${budget.amount} ${budget.token_symbol} (atomic units)`;
+  return `${amount} ${describeResetPeriod(budget.reset_period_min)}`;
+}
+async function waitForBudgetApproval(api, setupId, apiKey, log, options = {}) {
+  const intervalMs = options.intervalMs ?? 5e3;
+  const timeoutMs = options.timeoutMs ?? 18e4;
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve8) => setTimeout(resolve8, ms)));
+  const maxPolls = Math.max(1, Math.floor(timeoutMs / intervalMs));
+  const remindEvery = Math.max(1, Math.floor(3e4 / intervalMs));
+  log("Registered with Haven \u2014 waiting for you to approve the budget in the dashboard\u2026");
+  for (let i = 0; i < maxPolls; i++) {
+    await sleep(intervalMs);
+    let status;
+    try {
+      status = await api.getConnectorStatus(setupId, apiKey);
+    } catch (err) {
+      if (err instanceof ConnectRequestError && (err.status === 401 || err.status === 404)) {
+        log("This setup ended in Haven \u2014 start a fresh connection from the dashboard when ready.");
+        return "ended";
+      }
+      continue;
+    }
+    if (status.status === "active") {
+      log(
+        status.approved_budget ? `Budget approved \u{1F389} \u2014 I can now spend up to ${describeApprovedBudget(status.approved_budget)} from your Haven wallet.` : "Budget approved \u{1F389} \u2014 the agent can now spend within its Haven rules."
+      );
+      return "approved";
+    }
+    if (status.status === "cancelled" || status.status === "expired" || status.status === "failed") {
+      log(`This setup ended in Haven (${status.status}) \u2014 start a fresh connection from the dashboard when ready.`);
+      return "ended";
+    }
+    if ((i + 1) % remindEvery === 0) {
+      log("Still waiting for budget approval in Haven\u2026");
     }
-  } else {
-    log("After you approve, the Haven tools should appear in this runtime shortly.");
   }
+  log(
+    "Budget approval is still pending in Haven. Approve it in the dashboard whenever you are ready \u2014 the agent tools unlock the moment you do. Verify later with the read-only haven_get_agent tool."
+  );
+  return "pending";
+}
+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
@@ -2095,10 +2289,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") {
@@ -2125,7 +2322,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.");
@@ -2134,7 +2331,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 [
@@ -2156,9 +2353,10 @@ function helpText() {
     "  --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) {
@@ -2168,7 +2366,66 @@ 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, waitForApproval: !parsed.json },
+      {
+        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;
+}
+function isCliEntrypoint(argvPath = process.argv[1], moduleUrl = import.meta.url) {
+  if (!argvPath) return false;
+  try {
+    return realpathSync(argvPath) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return pathToFileURL(argvPath).href === moduleUrl;
+  }
+}
+if (isCliEntrypoint()) 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