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

package/README.md

@@ -33,14 +33,54 @@ identity) plus a separate local signer. The API key identifies the agent; the
 locally held signer key and the user's approved Haven wallet rules remain the
 spending authority.
 
-| Runtime | Configuration written by setup | Reload behaviour |
+| Runtime | Configuration written by setup | Activate the new entry |
 | --- | --- | --- |
-| Claude Code | User MCP registry | Start a new session |
-| Codex CLI / Codex Desktop | `~/.codex/config.toml` | Start a new session / restart the app |
-| Cursor | Cursor MCP configuration | Reloads automatically |
-| VS Code / VS Code Insiders | VS Code MCP configuration | Reloads automatically |
-| Claude Desktop | Claude Desktop MCP configuration | Restart the app |
-| Hermes Agent | `$HERMES_HOME/config.yaml` + `.env`, or `~/.hermes/config.yaml` + `.env` | Start a new session; gateway users run `/restart` |
+| Claude Code | User MCP registry | Start a new Claude Code session. |
+| Codex CLI | `~/.codex/config.toml` | Start a fresh session, for example `codex resume --last`. |
+| Codex Desktop | `~/.codex/config.toml` | Quit and reopen the app. |
+| Cursor | Cursor MCP configuration | Wait for hot reload; no app restart is required. |
+| VS Code / VS Code Insiders | VS Code MCP configuration | Wait for hot reload; no app restart is required. |
+| Claude Desktop | Claude Desktop MCP configuration | Quit and reopen the app. |
+| Hermes Agent | `$HERMES_HOME/config.yaml` + `.env`, or `~/.hermes/config.yaml` + `.env` | Start a new session; gateway users run `/restart`. |
+
+## After setup
+
+1. Return to Haven and approve the agent rules. Approval — not restarting —
+   unlocks the Haven tools.
+2. Activate the runtime using the table above.
+3. In the activated runtime, 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.
+
+### Structured output for automation
+
+Pass `--json` when a launcher needs a machine-readable completion record. Connect
+writes progress and human recovery notes to stderr and exactly one JSON object
+to stdout, with `schema_version: 1` and `outcome` set to `complete`,
+`action_required`, or `failed`. The object includes runtime/topology status,
+probe result, activation and next-action guidance, approval state/expiry (null
+when the backend does not provide an approval expiry), and the two
+read-only verification tools. It contains no API key, private key, credential
+contents, full credential paths, or full delegate address. The same redacted
+object is available to library callers as `runConnect(...).outcome`; the older
+fields remain for additive compatibility.
+
+For a recoverable install, configuration, probe, consent, or manual-runtime
+condition, inspect `error.code` and `error.next_action`, then follow the safe
+next action. A failed setup emits `outcome: "failed"` with a stable error code;
+it never presents credential material as a recovery diagnostic.
+
+If the setup challenge expires, return to Haven to start a fresh connection and
+rerun Connect. If a runtime write, installation, or probe fails, follow the
+structured `error.next_action` (or its human equivalent). The `other` runtime
+is the manual exception: finish the secret-free file-reference setup it prints,
+then start a fresh runtime session. Do not manually edit managed runtime
+configuration or paste credentials into prompts, logs, or configuration files.
+
+Connect abbreviates the public delegate address in normal output. Operators who
+need its full public identifier can inspect the owner-only, non-secret
+`agent.json` orientation file that Connect reports; do not inspect or share
+`identity.json` or `signer.json` for diagnostics because they contain secrets.
 
 For Hermes, Connect stores the hosted-MCP API key in the matching owner-only
 `.env` file and keeps only `Bearer ${MCP_HAVEN_API_KEY}` in `config.yaml`.

package/dist/cli.cjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
+var url = require('url');
 var crypto = require('crypto');
 var ethers = require('ethers');
 var promises = require('fs/promises');
@@ -13,6 +14,7 @@ var mcp = require('@haven_ai/mcp');
 var sdk = require('@haven_ai/sdk');
 var signer = require('@haven_ai/signer');
 
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var crypto__default = /*#__PURE__*/_interopDefault(crypto);
@@ -181,11 +183,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
     );
@@ -237,9 +240,9 @@ var MCP_RUNTIME_MANIFEST = {
   mcpPackage: "@haven_ai/mcp",
   mcpVersion: mcp.MCP_VERSION,
   sdkPackage: "@haven_ai/sdk",
-  sdkVersion: "0.1.22-alpha.0",
+  sdkVersion: "0.1.23-alpha.0",
   signerPackage: "@haven_ai/signer",
-  signerVersion: "0.1.22-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
@@ -1401,55 +1404,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 = {
@@ -1501,8 +1513,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();
@@ -1688,11 +1701,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 {
@@ -1711,7 +1725,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) {
@@ -1872,6 +1886,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";
@@ -1923,13 +1941,17 @@ function localRuntimePrepareErrorCode(err) {
 }
 
 // src/runtime.ts
-var CONNECTOR_VERSION = "0.1.22-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;
@@ -1950,6 +1972,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.");
@@ -1958,21 +1981,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({
@@ -2049,7 +2082,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) {
@@ -2062,10 +2157,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 secureLogger(log) {
-  return (message) => log(redactSecrets(message));
+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 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);
@@ -2082,17 +2193,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
@@ -2102,10 +2226,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") {
@@ -2132,7 +2259,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.");
@@ -2141,7 +2268,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 [
@@ -2163,9 +2290,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) {
@@ -2177,19 +2305,55 @@ function requireValue(argv, index, option) {
 }
 
 // src/cli.ts
-async function main() {
-  const parsed = parseArgs(process.argv.slice(2));
+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) {
-    process.stdout.write(`${helpText()}
+    io.stdout(`${helpText()}
 `);
-    return;
+    return 0;
   }
-  await runConnect(parsed.options);
-}
-main().catch((err) => {
-  process.stderr.write(`${err instanceof Error ? err.message : String(err)}
+  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))}
 `);
-  process.exit(1);
-});
+    } 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] && url.pathToFileURL(process.argv[1]).href === (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli.cjs', document.baseURI).href))) void main();
+
+exports.runCli = runCli;
 //# sourceMappingURL=cli.cjs.map
 //# sourceMappingURL=cli.cjs.map