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

package/dist/cli.d.cts

@@ -1 +1,8 @@
 #!/usr/bin/env node
+interface CliIo {
+    stdout: (message: string) => void;
+    stderr: (message: string) => void;
+}
+declare function runCli(argv: string[], io?: CliIo): Promise<number>;
+
+export { type CliIo, runCli };

package/dist/cli.d.ts

@@ -1 +1,8 @@
 #!/usr/bin/env node
+interface CliIo {
+    stdout: (message: string) => void;
+    stderr: (message: string) => void;
+}
+declare function runCli(argv: string[], io?: CliIo): Promise<number>;
+
+export { type CliIo, runCli };

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { pathToFileURL } from 'url';
 import crypto from 'crypto';
 import { Wallet } from 'ethers';
 import { mkdir, rm, chmod, access, writeFile, readFile, unlink } from 'fs/promises';
@@ -175,11 +176,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
     );
@@ -231,9 +233,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.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
@@ -1395,55 +1397,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 = {
@@ -1495,8 +1506,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();
@@ -1682,11 +1694,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 {
@@ -1705,7 +1718,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) {
@@ -1866,6 +1879,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";
@@ -1917,13 +1934,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;
@@ -1944,6 +1965,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.");
@@ -1952,21 +1974,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({
@@ -2043,7 +2075,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) {
@@ -2056,10 +2150,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);
@@ -2076,17 +2186,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
@@ -2096,10 +2219,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") {
@@ -2126,7 +2252,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.");
@@ -2135,7 +2261,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 [
@@ -2157,9 +2283,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) {
@@ -2171,19 +2298,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] && pathToFileURL(process.argv[1]).href === import.meta.url) void main();
+
+export { runCli };
 //# sourceMappingURL=cli.js.map
 //# sourceMappingURL=cli.js.map