@haven_ai/connect 0.1.30-alpha.0 → 0.1.31-alpha.0

package/dist/index.d.cts

@@ -203,8 +203,8 @@ interface RuntimeProfile {
 }
 declare function runtimeProfile(runtime: string | undefined, env?: NodeJS.ProcessEnv): RuntimeProfile;
 declare function normalizeRuntime(runtime: string | undefined, env?: NodeJS.ProcessEnv): RuntimeId;
-/** The flag values a refusal message should offer. Mirrors RuntimeId. */
-declare const RUNTIME_FLAG_VALUES: "claude-code, codex-cli, codex-desktop, cursor, vscode, vscode-insiders, claude-desktop, hermes, other";
+/** The same values as refusal-message prose. */
+declare const RUNTIME_FLAG_VALUES: string;
 interface RuntimeSelection {
     runtime: RuntimeId | null;
     source: 'force' | 'detected' | 'explicit' | 'prompted' | 'none';
@@ -447,7 +447,7 @@ declare function runtimeInstallCapabilities(runtime: string | undefined, env?: N
     restartRequired: boolean;
 };
 
-declare const CONNECTOR_VERSION = "0.1.30-alpha.0";
+declare const CONNECTOR_VERSION = "0.1.31-alpha.0";
 interface ConnectOptions {
     setupToken: string;
     apiBaseUrl: string;
@@ -515,9 +515,19 @@ interface ConnectOutcome {
     };
     delegate_address?: string;
     setup_challenge_expires_at?: string;
+    /**
+     * #2091, additive within schema_version 1: `message` is the redacted human
+     * refusal (automation used to get code + next_action and nothing to act
+     * on), and `allowed_runtimes` carries the valid `--runtime` retry values on
+     * runtime-selection refusals — the list the backend's setup prompt requires
+     * a retry to be drawn from, which `--json` previously discarded with the
+     * prose.
+     */
     error?: {
         code: string;
         next_action: string;
+        message?: string;
+        allowed_runtimes?: readonly string[];
     };
 }
 interface ConnectDeps {
@@ -555,13 +565,18 @@ declare function completionOutcome(input: {
     approvalRequired: boolean;
 }): ConnectOutcome;
 /**
- * A deliberately terse failure record: error messages can contain server or
- * filesystem detail, while this public contract must remain safe to serialize.
+ * The failure record for the `--json` contract.
  *
  * #1719: a `ConnectError` carries its own code and next action, so it is read
  * rather than guessed. The regex ladder below survives only for the refusals
  * that are still plain `Error`s — every new failure mode joins the vocabulary
  * instead of joining that ladder.
+ *
+ * #2091: the record now carries the redacted message rather than omitting it.
+ * The old stance — terse because "messages can contain server or filesystem
+ * detail" — left automation with a code and nothing to act on; the field
+ * failure was a Codex agent staring at `connect_failed` with, in its own
+ * words, "no additional safe error detail". Sanitize, don't silence.
  */
 declare function failedConnectOutcome(runtimeHint: string | undefined, error: unknown): ConnectOutcome;
 /**
@@ -634,10 +649,22 @@ declare function shortAddress(address: string): string;
  * Codes are additive and never renamed: a consumer pinned to an older
  * connector must keep recognising the ones it already knows.
  */
+interface ConnectErrorDetails {
+    /**
+     * The `--runtime` values a retry may use, when the refusal is about runtime
+     * selection (#2091). The values lived only in `message` prose, which the
+     * `--json` contract discards entirely — while the backend's setup prompt
+     * instructs an agent to retry only with "one of the values that refusal
+     * lists". Carrying them structurally is what makes that retry reachable
+     * from automation.
+     */
+    allowedRuntimes?: readonly string[];
+}
 declare class ConnectError extends Error {
     readonly code: string;
     readonly nextAction: string;
-    constructor(code: string, message: string, nextAction: string);
+    readonly details: ConnectErrorDetails;
+    constructor(code: string, message: string, nextAction: string, details?: ConnectErrorDetails);
 }
 declare function isConnectError(err: unknown): err is ConnectError;
 
@@ -697,11 +724,11 @@ declare function resolveRuntimeByInstalledClientPrompt(options?: ScanInstalledCl
 
 declare const MCP_RUNTIME_MANIFEST: {
     readonly mcpPackage: "@haven_ai/mcp";
-    readonly mcpVersion: "0.1.30-alpha.0";
+    readonly mcpVersion: "0.1.31-alpha.0";
     readonly sdkPackage: "@haven_ai/sdk";
-    readonly sdkVersion: "0.1.30-alpha.0";
+    readonly sdkVersion: "0.1.31-alpha.0";
     readonly signerPackage: "@haven_ai/signer";
-    readonly signerVersion: "0.1.30-alpha.0";
+    readonly signerVersion: "0.1.31-alpha.0";
     readonly minimumNodeVersion: "22.0.0";
     readonly supportedClients: readonly ["codex-cli", "codex-desktop", "claude-code"];
     readonly requiredTools: readonly string[];

package/dist/index.d.ts

@@ -203,8 +203,8 @@ interface RuntimeProfile {
 }
 declare function runtimeProfile(runtime: string | undefined, env?: NodeJS.ProcessEnv): RuntimeProfile;
 declare function normalizeRuntime(runtime: string | undefined, env?: NodeJS.ProcessEnv): RuntimeId;
-/** The flag values a refusal message should offer. Mirrors RuntimeId. */
-declare const RUNTIME_FLAG_VALUES: "claude-code, codex-cli, codex-desktop, cursor, vscode, vscode-insiders, claude-desktop, hermes, other";
+/** The same values as refusal-message prose. */
+declare const RUNTIME_FLAG_VALUES: string;
 interface RuntimeSelection {
     runtime: RuntimeId | null;
     source: 'force' | 'detected' | 'explicit' | 'prompted' | 'none';
@@ -447,7 +447,7 @@ declare function runtimeInstallCapabilities(runtime: string | undefined, env?: N
     restartRequired: boolean;
 };
 
-declare const CONNECTOR_VERSION = "0.1.30-alpha.0";
+declare const CONNECTOR_VERSION = "0.1.31-alpha.0";
 interface ConnectOptions {
     setupToken: string;
     apiBaseUrl: string;
@@ -515,9 +515,19 @@ interface ConnectOutcome {
     };
     delegate_address?: string;
     setup_challenge_expires_at?: string;
+    /**
+     * #2091, additive within schema_version 1: `message` is the redacted human
+     * refusal (automation used to get code + next_action and nothing to act
+     * on), and `allowed_runtimes` carries the valid `--runtime` retry values on
+     * runtime-selection refusals — the list the backend's setup prompt requires
+     * a retry to be drawn from, which `--json` previously discarded with the
+     * prose.
+     */
     error?: {
         code: string;
         next_action: string;
+        message?: string;
+        allowed_runtimes?: readonly string[];
     };
 }
 interface ConnectDeps {
@@ -555,13 +565,18 @@ declare function completionOutcome(input: {
     approvalRequired: boolean;
 }): ConnectOutcome;
 /**
- * A deliberately terse failure record: error messages can contain server or
- * filesystem detail, while this public contract must remain safe to serialize.
+ * The failure record for the `--json` contract.
  *
  * #1719: a `ConnectError` carries its own code and next action, so it is read
  * rather than guessed. The regex ladder below survives only for the refusals
  * that are still plain `Error`s — every new failure mode joins the vocabulary
  * instead of joining that ladder.
+ *
+ * #2091: the record now carries the redacted message rather than omitting it.
+ * The old stance — terse because "messages can contain server or filesystem
+ * detail" — left automation with a code and nothing to act on; the field
+ * failure was a Codex agent staring at `connect_failed` with, in its own
+ * words, "no additional safe error detail". Sanitize, don't silence.
  */
 declare function failedConnectOutcome(runtimeHint: string | undefined, error: unknown): ConnectOutcome;
 /**
@@ -634,10 +649,22 @@ declare function shortAddress(address: string): string;
  * Codes are additive and never renamed: a consumer pinned to an older
  * connector must keep recognising the ones it already knows.
  */
+interface ConnectErrorDetails {
+    /**
+     * The `--runtime` values a retry may use, when the refusal is about runtime
+     * selection (#2091). The values lived only in `message` prose, which the
+     * `--json` contract discards entirely — while the backend's setup prompt
+     * instructs an agent to retry only with "one of the values that refusal
+     * lists". Carrying them structurally is what makes that retry reachable
+     * from automation.
+     */
+    allowedRuntimes?: readonly string[];
+}
 declare class ConnectError extends Error {
     readonly code: string;
     readonly nextAction: string;
-    constructor(code: string, message: string, nextAction: string);
+    readonly details: ConnectErrorDetails;
+    constructor(code: string, message: string, nextAction: string, details?: ConnectErrorDetails);
 }
 declare function isConnectError(err: unknown): err is ConnectError;
 
@@ -697,11 +724,11 @@ declare function resolveRuntimeByInstalledClientPrompt(options?: ScanInstalledCl
 
 declare const MCP_RUNTIME_MANIFEST: {
     readonly mcpPackage: "@haven_ai/mcp";
-    readonly mcpVersion: "0.1.30-alpha.0";
+    readonly mcpVersion: "0.1.31-alpha.0";
     readonly sdkPackage: "@haven_ai/sdk";
-    readonly sdkVersion: "0.1.30-alpha.0";
+    readonly sdkVersion: "0.1.31-alpha.0";
     readonly signerPackage: "@haven_ai/signer";
-    readonly signerVersion: "0.1.30-alpha.0";
+    readonly signerVersion: "0.1.31-alpha.0";
     readonly minimumNodeVersion: "22.0.0";
     readonly supportedClients: readonly ["codex-cli", "codex-desktop", "claude-code"];
     readonly requiredTools: readonly string[];

package/dist/index.js

@@ -146,6 +146,9 @@ var init_key = __esm({
 function redactSecrets(value) {
   return value.replace(API_KEY_RE, "sk_agent_[redacted]").replace(PRIVATE_KEY_RE, "0x[redacted-private-key]");
 }
+function redactForAutomation(value) {
+  return redactSecrets(value).replace(/(?:~|\/)[^\s`"']*\/(?:identity|signer|agent)\.json\b/g, "[credential-file-redacted]").replace(/(?:~|\/)[^\s`"']*\/\.env\b/g, "[credential-env-redacted]");
+}
 function shortAddress(address) {
   if (!/^0x[0-9a-fA-F]{40}$/.test(address)) return address;
   return `${address.slice(0, 6)}...${address.slice(-4)}`;
@@ -516,9 +519,9 @@ var init_runtime_manifest = __esm({
       mcpPackage: "@haven_ai/mcp",
       mcpVersion: MCP_VERSION,
       sdkPackage: "@haven_ai/sdk",
-      sdkVersion: "0.1.30-alpha.0",
+      sdkVersion: "0.1.31-alpha.0",
       signerPackage: "@haven_ai/signer",
-      signerVersion: "0.1.30-alpha.0",
+      signerVersion: "0.1.31-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
@@ -1941,11 +1944,13 @@ var init_connect_error = __esm({
     ConnectError = class extends Error {
       code;
       nextAction;
-      constructor(code, message, nextAction2) {
+      details;
+      constructor(code, message, nextAction2, details = {}) {
         super(message);
         this.name = "ConnectError";
         this.code = code;
         this.nextAction = nextAction2;
+        this.details = details;
       }
     };
   }
@@ -1968,7 +1973,8 @@ async function resolveRuntimeSelection(explicit, force, options = {}) {
       throw new ConnectError(
         "runtime_force_unrecognized",
         `Unknown --runtime-force value "${force}". Valid values: ${RUNTIME_FLAG_VALUES}.`,
-        "rerun_connect_with_a_valid_runtime_name"
+        "rerun_connect_with_a_valid_runtime_name",
+        { allowedRuntimes: RUNTIME_FLAG_VALUE_LIST }
       );
     }
     return { runtime: forced, source: "force" };
@@ -1981,7 +1987,8 @@ async function resolveRuntimeSelection(explicit, force, options = {}) {
       throw new ConnectError(
         "runtime_unrecognized",
         `"${supplied}" is not an agent runtime Haven knows. Valid values: ${RUNTIME_FLAG_VALUES} (the aliases cowork, codex and openclaw are accepted too). Re-run with one of those, or --runtime other to store credentials and finish the MCP setup by hand. Nothing was written and the Haven setup token is still unused.`,
-        "rerun_connect_with_a_valid_runtime_name"
+        "rerun_connect_with_a_valid_runtime_name",
+        { allowedRuntimes: RUNTIME_FLAG_VALUE_LIST }
       );
     }
     return { runtime: detected, source: "detected", discardedHint: supplied };
@@ -2016,7 +2023,7 @@ function detectRuntime(env) {
   if (env.HERMES_HOME || env.HERMES_AGENT) return "hermes";
   return null;
 }
-var RUNTIME_PROFILES, RUNTIME_ALIASES, RUNTIME_FLAG_VALUES;
+var RUNTIME_PROFILES, RUNTIME_ALIASES, RUNTIME_FLAG_VALUE_LIST, RUNTIME_FLAG_VALUES;
 var init_runtime_registry = __esm({
   "src/runtime-registry.ts"() {
     init_connect_error();
@@ -2135,7 +2142,18 @@ var init_runtime_registry = __esm({
       other: "other",
       manual: "other"
     };
-    RUNTIME_FLAG_VALUES = "claude-code, codex-cli, codex-desktop, cursor, vscode, vscode-insiders, claude-desktop, hermes, other";
+    RUNTIME_FLAG_VALUE_LIST = [
+      "claude-code",
+      "codex-cli",
+      "codex-desktop",
+      "cursor",
+      "vscode",
+      "vscode-insiders",
+      "claude-desktop",
+      "hermes",
+      "other"
+    ];
+    RUNTIME_FLAG_VALUES = RUNTIME_FLAG_VALUE_LIST.join(", ");
   }
 });
 async function acknowledgeLocalSignerConsent(signerPath, log) {
@@ -3698,7 +3716,7 @@ function defaultPromptIo() {
 // src/runtime.ts
 init_local_mcp_runtime();
 init_runtime_manifest();
-var CONNECTOR_VERSION = "0.1.30-alpha.0";
+var CONNECTOR_VERSION = "0.1.31-alpha.0";
 var CONNECT_OUTCOME_SCHEMA_VERSION = 1;
 async function runConnect(options, deps = {}) {
   assertSupportedNodeVersion(deps.nodeVersion, MCP_RUNTIME_MANIFEST.minimumNodeVersion);
@@ -3723,7 +3741,14 @@ async function runConnect(options, deps = {}) {
     throw new ConnectError(
       "runtime_undetermined",
       `Could not determine the agent runtime: nothing was detected in this environment and no --runtime was given. If you are an AI agent running this command: re-run it once, unchanged except for adding --runtime <name>, naming the harness you are running in \u2014 one of: ${RUNTIME_FLAG_VALUES} (the aliases cowork, codex and openclaw are accepted too). Do not guess: if your harness is not one of those, use --runtime other, which stores the credentials and prints the manual MCP steps. Nothing was written and the Haven setup token is still unused.`,
-      "rerun_connect_with_explicit_runtime"
+      "rerun_connect_with_explicit_runtime",
+      // #2091: the values must ride structurally too. The backend's setup
+      // prompt permits a retry only with "one of the values that refusal
+      // lists" — and --json discards prose, so a prose-only list deadlocked
+      // every automation run in an undetected runtime (Codex in the field:
+      // npx needs network, Codex runs network commands unsandboxed, and the
+      // unsandboxed path carries none of the CODEX_* detection vars).
+      { allowedRuntimes: RUNTIME_FLAG_VALUE_LIST }
     );
   }
   const runtime = selection.runtime;
@@ -3745,11 +3770,16 @@ async function runConnect(options, deps = {}) {
     log(`runtime: ${runtime} (chosen at the prompt \u2014 nothing was detected in this environment)`);
   }
   log("Warming up your connection to Haven\u2026");
-  const setup = await api.resolveSetup({
-    setupToken: options.setupToken,
-    connectorVersion,
-    runtime
-  });
+  let setup;
+  try {
+    setup = await api.resolveSetup({
+      setupToken: options.setupToken,
+      connectorVersion,
+      runtime
+    });
+  } catch (err) {
+    throw deadSetupTokenError(err) ?? err;
+  }
   assertSetupChallengeIsUsable(setup.challenge.expires_at);
   printSetupSummary(setup, log);
   await preflightStorage({ baseDir: options.credentialsDir, warn: log });
@@ -3786,6 +3816,8 @@ async function runConnect(options, deps = {}) {
       installCapabilities
     });
   } catch (err) {
+    const dead = deadSetupTokenError(err);
+    if (dead) throw dead;
     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."
@@ -3983,7 +4015,17 @@ function failedConnectOutcome(runtimeHint, error) {
       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 }
+    error: {
+      code,
+      next_action: nextAction2,
+      // Only a ConnectError's message enters the JSON record: the vocabulary's
+      // prose is connector-authored and safe to serialize, while a plain
+      // Error can carry arbitrary server or filesystem detail (that stance is
+      // pinned by test). Redaction stays on as belt-and-braces; plain-Error
+      // runs still get their redacted message on stderr via the CLI mirror.
+      ...error instanceof ConnectError && message ? { message: redactForAutomation(message) } : {},
+      ...error instanceof ConnectError && error.details.allowedRuntimes ? { allowed_runtimes: error.details.allowedRuntimes } : {}
+    }
   };
 }
 function printSetupSummary(setup, log) {
@@ -4005,16 +4047,20 @@ function assertSetupChallengeIsUsable(expiresAt) {
     "This Haven setup challenge is expired or invalid. Return to Haven, start a fresh connection, and rerun Connect. No local credentials were written."
   );
 }
+function deadSetupTokenError(err) {
+  if (!(err instanceof ConnectRequestError) || err.status !== 410 && err.status !== 401) return null;
+  return new ConnectError(
+    "setup_challenge_expired_or_invalid",
+    "This Haven setup token is expired or invalid \u2014 tokens are single-use and expire 30 minutes after the dashboard issues them, and a mistyped token reads the same way. Return to Haven, start a fresh connection, and run its new Connect command. No local credentials were written.",
+    "return_to_haven_for_fresh_setup"
+  );
+}
 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);
+    log(redactPaths ? redactForAutomation(message) : redactSecrets(message));
   };
 }
 function printRuntimeInstall(result, log) {
@@ -4358,6 +4404,8 @@ async function runCli(argv, io = {
     parsed = parseArgs(argv);
   } catch (err) {
     if (wantsJson) {
+      io.stderr(`${redactForAutomation(err instanceof Error ? err.message : String(err))}
+`);
       io.stdout(`${JSON.stringify(failedConnectOutcome(void 0, err))}
 `);
     } else {
@@ -4538,6 +4586,8 @@ async function runCli(argv, io = {
     return 0;
   } catch (err) {
     if (parsed.json) {
+      io.stderr(`${redactForAutomation(err instanceof Error ? err.message : String(err))}
+`);
       io.stdout(`${JSON.stringify(failedConnectOutcome(parsed.options.runtime, err))}
 `);
     } else {