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

package/dist/index.d.ts

@@ -190,6 +190,37 @@ interface PreflightCredentialStorageInput {
 declare function preflightCredentialStorage(input?: PreflightCredentialStorageInput): Promise<string>;
 declare function writeCredentialFiles(input: WriteCredentialInput): Promise<StoredCredentialPaths>;
 declare function defaultAgentDirectory(agentId: string, baseDir?: string): string;
+/**
+ * Where the terminal `ConnectOutcome` is parked so a caller that lost the
+ * stream can still read the verdict.
+ *
+ * The field failure this exists for (2026-08-28, connector 0.1.31-alpha.0):
+ * setup SUCCEEDED, but the agent driving it stopped watching during the cold
+ * signer install, so the connector's final `--json` object — the only place
+ * the restart instruction and the read-only verification sequence live — was
+ * emitted into a stream nobody was reading. The agent reverse-engineered
+ * completion from `codex mcp list` instead.
+ */
+declare const CONNECT_OUTCOME_FILENAME = "last-connect-outcome.json";
+/**
+ * Persist the terminal outcome next to the credentials it describes.
+ *
+ * Non-secret by construction: the content is exactly the object already
+ * emitted on stdout, whose secret-freedom is pinned by its own tests. This
+ * function never reads or embeds credential-file contents — it serializes what
+ * it is handed and nothing else. Written 0o600 anyway, because it lives inside
+ * a 0o700 credential directory and there is no reason to widen it.
+ *
+ * Overwrites, unlike every other write in this file: "the last outcome" is a
+ * single slot, not a credential, so `assertDoesNotExist` would be wrong here —
+ * a stale verdict left in place is exactly the failure the file exists to
+ * prevent.
+ *
+ * Throws on failure. Best-effort is the CALLER's contract (`runConnect` wraps
+ * both call sites), so that a test can inject a writer that fails and still
+ * assert the run completes.
+ */
+declare function writeConnectOutcomeRecord(directory: string, outcome: unknown, warn?: (message: string) => void): Promise<string>;
 
 type RuntimeId = 'claude-code' | 'codex-desktop' | 'codex-cli' | 'cursor' | 'vscode' | 'vscode-insiders' | 'claude-desktop' | 'hermes' | 'other';
 type RestartMode = 'restart-session' | 'restart-app' | 'hot-reload' | 'manual';
@@ -203,8 +234,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 +478,102 @@ declare function runtimeInstallCapabilities(runtime: string | undefined, env?: N
     restartRequired: boolean;
 };
 
-declare const CONNECTOR_VERSION = "0.1.30-alpha.0";
+/**
+ * Installed-client scan + interactive pick (#1719).
+ *
+ * The rung that answers "which runtime am I configuring?" for a HUMAN in a
+ * plain terminal, where there is no agent shell to detect. Two properties hold
+ * it up, and both are load-bearing:
+ *
+ * 1. **Only clients the connector can actually write.** A row that cannot be
+ *    configured is not a choice, it is a dead end wearing a choice's clothes.
+ * 2. **The scan populates the choices; it never selects.** Finding exactly one
+ *    installed app tells you what EXISTS, not where the user wants their agent
+ *    to run — and the cost of being wrong is an API key and a delegate key
+ *    written into an app the user does not use. `scanInstalledClients` returns
+ *    candidates and nothing else; only an answer typed at the prompt resolves
+ *    a runtime.
+ */
+interface InstalledClientCandidate {
+    runtime: RuntimeId;
+    label: string;
+    /** What made this a candidate — shown at the prompt so the pick is informed. */
+    detail: string;
+    /**
+     * The config file Haven would write for this client, when it owns one.
+     * `null` for Claude Code, which is configured through its own CLI. Set
+     * regardless of which evidence found the client — `evidence` is what says
+     * whether that file exists today.
+     */
+    configPath: string | null;
+    evidence: 'config-file' | 'client-directory';
+}
+interface ScanInstalledClientsOptions {
+    homeDir?: string;
+    /** Workspace root, for the project-local `.vscode/` marker. */
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Injectable so the scan is testable without a populated home directory. */
+    exists?: (path: string) => Promise<boolean>;
+}
+declare function scanInstalledClients(options?: ScanInstalledClientsOptions): Promise<InstalledClientCandidate[]>;
+/**
+ * The scan's findings as DATA, for the `--json` refusal (#2174).
+ *
+ * The interactive prompt is deliberately omitted under `--json`, which threw
+ * this signal away exactly where it was most useful: an agent retrying a
+ * `runtime_undetermined` refusal picked from a nine-value menu on
+ * self-knowledge alone, while the connector already knew which client configs
+ * exist on the machine.
+ *
+ * Property 2 above is preserved verbatim and is the reason this returns a
+ * HINT rather than a runtime: the caller still has to refuse. Finding exactly
+ * one installed app tells you what exists, not where the user wants their
+ * agent to run, and the cost of being wrong is an API key and a delegate key
+ * written into an app they do not use.
+ */
+interface InstalledClientHint {
+    /** Runtime ids the scan found, likeliest first. */
+    installedClients: readonly RuntimeId[];
+    /**
+     * The top hit, and only when it is unambiguously top — see
+     * `installedClientHint`. A value an agent may echo back as `--runtime`;
+     * never a selection the connector makes for it.
+     */
+    suggestedRuntime?: RuntimeId;
+}
+/**
+ * A suggestion is offered only when one candidate is CLEARLY first: a lone
+ * candidate, or a single live MCP config file among bare client directories —
+ * the one tier difference the scan treats as evidence. Candidates within a
+ * tier are separated only by `SCAN_ORDER`, a fixed preference rather than a
+ * fact about this machine, so suggesting the winner of that tiebreak would
+ * dress an arbitrary choice as a finding.
+ *
+ * The suggestion is derived from the WHOLE array rather than from the first
+ * two entries, so it does not depend on the caller having sorted anything.
+ * This is exported, and an unsorted list reaching a positional rule would
+ * yield a quietly wrong suggestion — never a selection, since only the caller
+ * can act on it, but wrong is still wrong. `installedClients` preserves the
+ * order it was given, which for `scanInstalledClients` is likeliest-first.
+ */
+declare function installedClientHint(candidates: readonly InstalledClientCandidate[]): InstalledClientHint;
+interface PromptIo {
+    write: (text: string) => void;
+    /** Resolves the typed line, or `null` on EOF / Ctrl-C. */
+    question: (query: string) => Promise<string | null>;
+}
+declare function promptForInstalledClient(candidates: readonly InstalledClientCandidate[], io?: PromptIo): Promise<RuntimeId>;
+/**
+ * The whole rung as one thunk: scan, refuse if nothing writable is installed,
+ * otherwise prompt. This is what `resolveRuntimeSelection` calls, which is why
+ * the registry needs no knowledge of the filesystem or of readline.
+ */
+declare function resolveRuntimeByInstalledClientPrompt(options?: ScanInstalledClientsOptions & {
+    io?: PromptIo;
+}): Promise<RuntimeId>;
+
+declare const CONNECTOR_VERSION = "0.1.32-alpha.0";
 interface ConnectOptions {
     setupToken: string;
     apiBaseUrl: string;
@@ -515,9 +641,57 @@ interface ConnectOutcome {
     };
     delegate_address?: string;
     setup_challenge_expires_at?: string;
+    /**
+     * #2173, additive within schema_version 1. Both are present on a completed
+     * run and absent on `failedConnectOutcome`, which by construction has
+     * neither a registration nor a credential scan behind it.
+     *
+     * `hosted_mcp_url` is the endpoint Connect wired this run up to — written
+     * into the runtime's MCP config, or, on a manual runtime that Connect cannot
+     * configure, printed as the endpoint to enter by hand. It is deliberately
+     * NOT the `--api` backend URL: the hosted MCP
+     * server is a separate deployment, and an automation caller comparing the
+     * two used to read that intentional topology as an environment mismatch. It
+     * is non-secret — the same string already sits in the user's own config file
+     * — and carries no credential; the API key travels beside it in a header.
+     *
+     * `superseded_agent_ids` is the #1688 heads-up made structural: previously
+     * it was prose on stderr, so a `--json` caller could not see that the run it
+     * just completed left older agents alive with their own keys. Empty on a
+     * clean first run. An empty list is NOT proof of a clean machine — a scan
+     * that cannot read the credential root also yields an empty list, and the
+     * connector prefers that to failing a completed setup.
+     */
+    hosted_mcp_url?: string;
+    superseded_agent_ids?: readonly 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[];
+        /**
+         * #2174, additive within schema_version 1. What the installed-client scan
+         * found on THIS machine, narrowing a `runtime_undetermined` retry from the
+         * nine-value `allowed_runtimes` menu to what is actually here.
+         *
+         * A hint an agent may echo back as `--runtime`, never a selection: the
+         * outcome stays `failed` with `rerun_connect_with_explicit_runtime`, and
+         * the connector never proceeds on it (#1719's populates-never-selects
+         * invariant). Absent when the scan found nothing OR could not run —
+         * both are honestly "no finding"; neither is a claim the machine is bare.
+         * `suggested_runtime` appears only when one candidate is unambiguously
+         * top, so it is never the winner of an arbitrary tiebreak.
+         */
+        installed_clients?: readonly string[];
+        suggested_runtime?: string;
     };
 }
 interface ConnectDeps {
@@ -538,6 +712,19 @@ interface ConnectDeps {
     isTty?: boolean;
     /** Overridable so the #1719 installed-client prompt is testable without readline. */
     promptRuntime?: () => Promise<RuntimeId>;
+    /**
+     * Overridable so the #2173 recovery-record write is testable without a real
+     * credential directory — and so a FAILING writer can be injected to prove
+     * that a broken record write never fails a completed setup.
+     */
+    writeOutcomeRecord?: typeof writeConnectOutcomeRecord;
+    /**
+     * Overridable so the #2174 refusal hint is testable without depending on
+     * which agent clients happen to be installed on the machine running the
+     * suite — and so a THROWING scan can be injected to prove the refusal
+     * degrades to its un-hinted shape.
+     */
+    scanInstalledClients?: typeof scanInstalledClients;
 }
 interface ConnectResult {
     setupId: string;
@@ -547,21 +734,35 @@ interface ConnectResult {
     /** Additive, secret-free completion contract shared by library callers and --json. */
     outcome: ConnectOutcome;
 }
+/**
+ * The failure record for an error thrown by `runConnect` — the run's own, when
+ * it built one, and a freshly derived record otherwise (a rejection that never
+ * entered the run at all, such as an argument-parse refusal, or an injected
+ * one in a test).
+ */
+declare function failureOutcomeFor(runtimeHint: string | undefined, error: unknown): ConnectOutcome;
 declare function runConnect(options: ConnectOptions, deps?: ConnectDeps): Promise<ConnectResult>;
 declare function completionOutcome(input: {
     runtimeInstall: RuntimeInstallResult;
     delegateAddress: string;
+    hostedMcpUrl?: string;
+    supersededAgentIds?: readonly string[];
     setupChallengeExpiresAt?: string;
     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;
 /**
@@ -600,6 +801,17 @@ interface ParsedCli {
         reason?: string;
         replacedBy?: string;
     };
+    /**
+     * #2169: unwire one agent — tombstone it, then remove its MCP pair and
+     * Hermes dotenv key from every runtime config. No token required; refuses
+     * rather than guess when a bare pair is owned by a different agent.
+     */
+    unwire?: {
+        reason?: string;
+        replacedBy?: string;
+    };
+    /** Optional positional value of --unwire <dir> (else --name / --credentials-dir resolve it). */
+    unwireDir?: string;
     /**
      * #1700: replace an agent's signing key on this machine. Two phases, because
      * the dashboard sits between them — `start` generates the key and prints its
@@ -634,74 +846,44 @@ 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[];
+    /**
+     * What the #1719 installed-client scan found on this machine (#2174), when
+     * the refusal is `runtime_undetermined`. `installedClients` is ordered
+     * likeliest-first; `suggestedRuntime` appears only when one candidate is
+     * unambiguously top.
+     *
+     * A HINT, never a decision. The scan populates choices and never selects —
+     * carrying it here does not let the connector proceed on it, and the retry
+     * stays the agent's explicit `--runtime <name>`.
+     */
+    installedClients?: readonly string[];
+    suggestedRuntime?: 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;
 
-/**
- * Installed-client scan + interactive pick (#1719).
- *
- * The rung that answers "which runtime am I configuring?" for a HUMAN in a
- * plain terminal, where there is no agent shell to detect. Two properties hold
- * it up, and both are load-bearing:
- *
- * 1. **Only clients the connector can actually write.** A row that cannot be
- *    configured is not a choice, it is a dead end wearing a choice's clothes.
- * 2. **The scan populates the choices; it never selects.** Finding exactly one
- *    installed app tells you what EXISTS, not where the user wants their agent
- *    to run — and the cost of being wrong is an API key and a delegate key
- *    written into an app the user does not use. `scanInstalledClients` returns
- *    candidates and nothing else; only an answer typed at the prompt resolves
- *    a runtime.
- */
-interface InstalledClientCandidate {
-    runtime: RuntimeId;
-    label: string;
-    /** What made this a candidate — shown at the prompt so the pick is informed. */
-    detail: string;
-    /**
-     * The config file Haven would write for this client, when it owns one.
-     * `null` for Claude Code, which is configured through its own CLI. Set
-     * regardless of which evidence found the client — `evidence` is what says
-     * whether that file exists today.
-     */
-    configPath: string | null;
-    evidence: 'config-file' | 'client-directory';
-}
-interface ScanInstalledClientsOptions {
-    homeDir?: string;
-    /** Workspace root, for the project-local `.vscode/` marker. */
-    cwd?: string;
-    env?: NodeJS.ProcessEnv;
-    /** Injectable so the scan is testable without a populated home directory. */
-    exists?: (path: string) => Promise<boolean>;
-}
-declare function scanInstalledClients(options?: ScanInstalledClientsOptions): Promise<InstalledClientCandidate[]>;
-interface PromptIo {
-    write: (text: string) => void;
-    /** Resolves the typed line, or `null` on EOF / Ctrl-C. */
-    question: (query: string) => Promise<string | null>;
-}
-declare function promptForInstalledClient(candidates: readonly InstalledClientCandidate[], io?: PromptIo): Promise<RuntimeId>;
-/**
- * The whole rung as one thunk: scan, refuse if nothing writable is installed,
- * otherwise prompt. This is what `resolveRuntimeSelection` calls, which is why
- * the registry needs no knowledge of the filesystem or of readline.
- */
-declare function resolveRuntimeByInstalledClientPrompt(options?: ScanInstalledClientsOptions & {
-    io?: PromptIo;
-}): Promise<RuntimeId>;
-
 declare const MCP_RUNTIME_MANIFEST: {
     readonly mcpPackage: "@haven_ai/mcp";
-    readonly mcpVersion: "0.1.30-alpha.0";
+    readonly mcpVersion: "0.1.32-alpha.0";
     readonly sdkPackage: "@haven_ai/sdk";
-    readonly sdkVersion: "0.1.30-alpha.0";
+    readonly sdkVersion: "0.1.32-alpha.0";
     readonly signerPackage: "@haven_ai/signer";
-    readonly signerVersion: "0.1.30-alpha.0";
+    readonly signerVersion: "0.1.32-alpha.0";
     readonly minimumNodeVersion: "22.0.0";
     readonly supportedClients: readonly ["codex-cli", "codex-desktop", "claude-code"];
     readonly requiredTools: readonly string[];
@@ -717,4 +899,4 @@ declare function mcpPackageSpec(): string;
 declare function sdkPackageSpec(): string;
 declare function signerPackageSpec(): string;
 
-export { CONNECTOR_VERSION, CONNECT_OUTCOME_SCHEMA_VERSION, type ConnectApiClient, type ConnectDeps, ConnectError, type ConnectOptions, type ConnectOutcome, type ConnectOutcomeStatus, type ConnectResult, type InstalledClientCandidate, type LocalDelegateKey, MCP_RUNTIME_MANIFEST, type ParsedCli, type PrepareSignerRuntimeInput, type PreparedSignerRuntime, type PromptIo, RUNTIME_FLAG_VALUES, type RegisterSetupInput, type RegisterSetupResponse, type ResolveSetupInput, type ResolvedSetup, type RuntimeId, type RuntimeInstallInput, type RuntimeInstallResult, type RuntimeProfile, type RuntimeResolutionOptions, type RuntimeSelection, type ScanInstalledClientsOptions, type StoredCredentialPaths, type UpdateInstallStatusInput, type WriteCredentialInput, completionOutcome, createConnectApiClient, defaultAgentDirectory, delegateKeyFromPrivateKey, failedConnectOutcome, generateDelegateKey, helpText, installRuntime, isConnectError, mcpPackageSpec, normalizeRuntime, parseArgs, prepareSignerRuntime, promptForInstalledClient, redactSecrets, resolveRuntimeByInstalledClientPrompt, resolveRuntimeSelection, runConnect, runtimeInstallCapabilities, runtimeProfile, scanInstalledClients, sdkPackageSpec, shortAddress, signerPackageSpec, writeCredentialFiles };
+export { CONNECTOR_VERSION, CONNECT_OUTCOME_FILENAME, CONNECT_OUTCOME_SCHEMA_VERSION, type ConnectApiClient, type ConnectDeps, ConnectError, type ConnectOptions, type ConnectOutcome, type ConnectOutcomeStatus, type ConnectResult, type InstalledClientCandidate, type InstalledClientHint, type LocalDelegateKey, MCP_RUNTIME_MANIFEST, type ParsedCli, type PrepareSignerRuntimeInput, type PreparedSignerRuntime, type PromptIo, RUNTIME_FLAG_VALUES, type RegisterSetupInput, type RegisterSetupResponse, type ResolveSetupInput, type ResolvedSetup, type RuntimeId, type RuntimeInstallInput, type RuntimeInstallResult, type RuntimeProfile, type RuntimeResolutionOptions, type RuntimeSelection, type ScanInstalledClientsOptions, type StoredCredentialPaths, type UpdateInstallStatusInput, type WriteCredentialInput, completionOutcome, createConnectApiClient, defaultAgentDirectory, delegateKeyFromPrivateKey, failedConnectOutcome, failureOutcomeFor, generateDelegateKey, helpText, installRuntime, installedClientHint, isConnectError, mcpPackageSpec, normalizeRuntime, parseArgs, prepareSignerRuntime, promptForInstalledClient, redactSecrets, resolveRuntimeByInstalledClientPrompt, resolveRuntimeSelection, runConnect, runtimeInstallCapabilities, runtimeProfile, scanInstalledClients, sdkPackageSpec, shortAddress, signerPackageSpec, writeConnectOutcomeRecord, writeCredentialFiles };