@haven_ai/connect 0.0.0-dev.202609031523.fd49e1a

package/dist/index.d.ts

@@ -0,0 +1,902 @@
+export { CliIo, runCli } from './cli.js';
+
+interface ConnectApiClient {
+    resolveSetup(input: ResolveSetupInput): Promise<ResolvedSetup>;
+    registerSetup(input: RegisterSetupInput): Promise<RegisterSetupResponse>;
+    updateInstallStatus(setupId: string, apiKey: string, input: UpdateInstallStatusInput): Promise<void>;
+    /**
+     * #1377 D: the narrow status read the connector polls after registering,
+     * authenticated with the agent API key it just minted (works while the
+     * agent is still `setup_pending` — the endpoint exists for exactly that
+     * window). Returns status plus the approved budget once approval lands;
+     * never any secret material.
+     */
+    getConnectorStatus(setupId: string, apiKey: string): Promise<ConnectorStatusResponse>;
+    /**
+     * #1700: the agent behind an API key. Used by the re-key flow on both sides
+     * of the dashboard hand-off — see {@link AgentIdentity}.
+     */
+    getAgentIdentity(apiKey: string): Promise<AgentIdentity>;
+}
+interface ConnectorStatusResponse {
+    status: string;
+    approved_budget: {
+        token_symbol: string;
+        token_address: string;
+        amount: string;
+        reset_period_min: number;
+    } | null;
+}
+interface ResolveSetupInput {
+    setupToken: string;
+    connectorVersion: string;
+    runtime?: string;
+}
+interface RegisterSetupInput extends ResolveSetupInput {
+    challengeId: string;
+    delegateAddress: string;
+    proofSignature: string;
+    apiKeyHash: string;
+    apiKeyPrefix: string;
+    /**
+     * #1878: the RESOLVED hosted MCP server name this agent is being wired as —
+     * `haven` for the bare pair, `haven-<slug>` for a named one. Sent so the
+     * dashboard can tell two agents in one harness apart; it is a display aid
+     * and Haven keys nothing off it.
+     *
+     * Always sent by a connector that supports it, bare pair included. Omitting
+     * it for the bare pair would make "absent" ambiguous between *this is the
+     * unnamed pair* and *an older connector said nothing*, and only the second
+     * of those may render as unknown.
+     */
+    mcpServerName?: string;
+    connectorContext?: ConnectorContext;
+    installCapabilities?: {
+        canWriteRuntimeConfig?: boolean;
+        restartRequired?: boolean;
+    };
+}
+interface UpdateInstallStatusInput {
+    runtime?: string;
+    connectorVersion: string;
+    runtimeMcpMode?: string;
+    hostedMcpConfigured: boolean;
+    localSignerConfigured: boolean;
+    localMcpConfigured?: boolean;
+    credentialFilesWritten?: boolean;
+    signerAcknowledged?: boolean;
+    localMcpAcknowledged?: boolean;
+    activationCommandAvailable?: boolean;
+    skillInstalled?: boolean;
+    /**
+     * Omitted on the #1543 early config-written report — no probe has run yet,
+     * and the backend merge keeps the key absent until the final report sets it.
+     */
+    probeResult?: string;
+    restartRequired: boolean;
+    nextUserAction: string;
+    errorCode?: string | null;
+    environmentLabel?: string;
+}
+interface ConnectorContext {
+    environment_label?: string;
+    runtime_version?: string;
+    config_target?: string;
+}
+interface ResolvedSetup {
+    setup_id: string;
+    status: string;
+    agent: {
+        name: string;
+        description?: string | null;
+    };
+    haven_wallet: {
+        id: string;
+        name: string;
+        address: string;
+        chain_id: number;
+        network: string;
+    };
+    agent_budget: Array<{
+        token_address: string;
+        token_symbol: string;
+        allowance_amount: string;
+        reset_period_min: number;
+    }>;
+    hosted_mcp_url: string;
+    x402_binding_signer?: string | null;
+    challenge: {
+        id: string;
+        message: string;
+        expires_at: string;
+    };
+}
+interface RegisterSetupResponse {
+    setup_id: string;
+    agent_id: string;
+    status: string;
+    agent_status: string;
+    api_key_prefix: string;
+    api_key_scope: string;
+    delegate_address: string;
+    hosted_mcp_url: string;
+    next_action: string;
+}
+/**
+ * The agent identity behind an API key (#1700).
+ *
+ * Read from `GET /machine-payments/agent`, the same agent-authenticated
+ * endpoint the SDK's `getAgent()` uses. Re-key needs it twice and for two
+ * different questions: BEFORE, to refuse a legacy-rail account the way the
+ * backend would rather than let the owner discover it five signed steps later;
+ * and AFTER, to prove the API key the owner pasted really belongs to this
+ * agent and really names the key this machine just generated.
+ */
+interface AgentIdentity {
+    id: string;
+    name: string;
+    status: string;
+    safe_address: string | null;
+    delegate_address: string | null;
+    chain_id: number | null;
+    execution_rail: 'legacy' | 'delegation' | string;
+}
+declare function createConnectApiClient(baseUrl: string, fetchImpl?: typeof fetch): ConnectApiClient;
+
+interface LocalDelegateKey {
+    privateKey: string;
+    address: string;
+    signChallenge(message: string): Promise<string>;
+}
+declare function generateDelegateKey(): LocalDelegateKey;
+declare function delegateKeyFromPrivateKey(privateKey: string): LocalDelegateKey;
+
+interface StoredCredentialPaths {
+    directory: string;
+    identityPath: string;
+    signerPath: string;
+    /** Non-secret orientation file (identity + configured budget, no keys). */
+    agentPath: string;
+}
+interface WriteCredentialInput {
+    baseDir?: string;
+    agentId: string;
+    /**
+     * #1696: wiring slug. Named agents live at ~/.haven/agents/<slug>/ (stable
+     * across a re-key by construction — the slug never rotates); unnamed keep
+     * the historical ~/.haven/agents/<agent-uuid>/. Both schemes coexist.
+     */
+    serverName?: string;
+    apiKey: string;
+    delegateKey: string;
+    delegateAddress: string;
+    safeAddress?: string;
+    chainId?: number;
+    network?: string;
+    agentBudget?: Array<{
+        token_symbol: string;
+        allowance_amount: string;
+        reset_period_min: number;
+    }>;
+    apiUrl: string;
+    hostedMcpUrl: string;
+    x402BindingSigner?: string;
+    warn?: (message: string) => void;
+}
+interface PreflightCredentialStorageInput {
+    baseDir?: string;
+    warn?: (message: string) => void;
+}
+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';
+interface RuntimeProfile {
+    id: RuntimeId;
+    label: string;
+    restartMode: RestartMode;
+    canWriteRuntimeConfig: boolean;
+    /** Precise, runtime-owned instruction for loading a freshly written MCP entry. */
+    activationInstruction: string;
+}
+declare function runtimeProfile(runtime: string | undefined, env?: NodeJS.ProcessEnv): RuntimeProfile;
+declare function normalizeRuntime(runtime: string | undefined, env?: NodeJS.ProcessEnv): RuntimeId;
+/** The same values as refusal-message prose. */
+declare const RUNTIME_FLAG_VALUES: string;
+interface RuntimeSelection {
+    runtime: RuntimeId | null;
+    source: 'force' | 'detected' | 'explicit' | 'prompted' | 'none';
+    /** Set when a confident environment detection overrode a contradicting explicit hint (#1672). */
+    overrodeHint?: RuntimeId;
+    /** Set when a supplied hint was not a runtime name at all and detection carried the run (#1719). */
+    discardedHint?: string;
+}
+interface RuntimeResolutionOptions {
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Rung 3b (#1719): the harness an AGENT executing this command reported for
+     * ITSELF, when detection found nothing to go on.
+     *
+     * It deliberately enters at the same precedence as `--runtime`, which is
+     * what makes it safe: a hint can only ever fill a vacuum, and loses to a
+     * confident detection exactly as #1672 made it. In practice the agent
+     * supplies it BY re-running with `--runtime <name>`; this field exists so a
+     * programmatic caller can pass a self-report without pretending to be a
+     * command-line flag, and so the ladder names the rung it has.
+     */
+    selfReported?: string;
+    /**
+     * Rung 4 (#1719): ask a human at an interactive terminal which of the
+     * clients installed on this machine to configure. Injected as a thunk so
+     * the ladder stays a policy function — the scan, the readline prompt, and
+     * the "nothing writable is installed" refusal all live in
+     * `installed-clients.ts`. Omitted (`--json`, no TTY, library callers) means
+     * the rung is skipped entirely, not answered with a guess.
+     */
+    promptForRuntime?: () => Promise<RuntimeId>;
+}
+/**
+ * Runtime resolution, detection-first (#1672) and self-resolving (#1719).
+ *
+ * The setup command carries no `--runtime`; the connector works out the
+ * runtime it is executing inside. Precedence:
+ *
+ * 1. `--runtime-force <name>` — always wins (unknown name refuses).
+ * 2. Environment detection over a CONTRADICTING hint. Detection only fires
+ *    inside a real agent shell, where writing a different client's config is
+ *    almost surely wrong — the claude-desktop-hint-in-Claude-Code dead end
+ *    this exists to close.
+ * 3. An explicit `--runtime`, or an agent's self-report, with no contradicting
+ *    detection (the legit plain-terminal "configure Claude Desktop by hand"
+ *    case — unchanged).
+ * 4. Detection alone.
+ * 5. An interactive pick among the clients actually installed here, when a
+ *    human is at a TTY. The scan populates the choices; it never selects.
+ * 6. Nothing known → `runtime: null`; the caller refuses BEFORE side effects
+ *    rather than guessing a config location.
+ *
+ * A hint that is not a runtime name at all is not a hint — it is a mistake, and
+ * the one thing it must never do is fall through to a config location nobody
+ * asked for. With no detection to fall back on it refuses (`runtime_unrecognized`).
+ * With a detection it loses to it, loudly, exactly like a contradicting hint:
+ * the detected client is the right write either way, and refusing there would
+ * turn every rollout window in which the dashboard learns an id before the
+ * published connector does into a hard failure.
+ */
+declare function resolveRuntimeSelection(explicit: string | undefined, force: string | undefined, options?: RuntimeResolutionOptions): Promise<RuntimeSelection>;
+
+type RuntimeMcpMode = 'local_stdio' | 'hosted_plus_signer' | 'manual';
+
+type LocalMcpProbeStatus = 'ok' | 'timeout' | 'process_error' | 'bad_response' | 'missing_tools';
+interface LocalMcpProbeResult {
+    status: LocalMcpProbeStatus;
+    /** #1589: the initialize response's serverInfo/capabilities, when reached —
+     *  the doctor reports the signer's advertised compat versions from here
+     *  instead of a second probe call. */
+    serverInfo?: {
+        name?: string;
+        version?: string;
+    };
+    capabilities?: Record<string, unknown>;
+    toolNames?: string[];
+}
+
+interface PrepareLocalMcpRuntimeInput {
+    credentialDirectory: string;
+    identityPath: string;
+    signerPath: string;
+    homeDir?: string;
+    nodeVersion?: string;
+    /** #1696: wiring slug, recorded in the sidecar for per-agent inventory (#1697). */
+    serverName?: string;
+}
+interface PreparedLocalMcpRuntime {
+    command: string;
+    args: string[];
+    wrapperPath: string;
+    runtimeDirectory: string;
+    npmCacheDirectory: string;
+    cliPath: string;
+    messages: string[];
+}
+
+interface PrepareSignerRuntimeInput {
+    credentialDirectory: string;
+    signerPath: string;
+    homeDir?: string;
+    /** #1696: wiring slug, recorded in the sidecar for per-agent inventory (#1697). */
+    serverName?: string;
+}
+interface PreparedSignerRuntime {
+    /** Absolute command to register as the signer MCP `command`. */
+    command: string;
+    /** Args to register alongside `command` (credentials are baked into the wrapper). */
+    args: string[];
+    wrapperPath: string;
+    runtimeDirectory: string;
+    npmCacheDirectory: string;
+    cliPath: string;
+    messages: string[];
+}
+interface SignerRuntimeDeps {
+    runCommand?: (command: string, args: string[]) => Promise<void>;
+    /** Heartbeats during the (possibly minutes-long) npm install (#1586). */
+    onProgress?: (message: string) => void;
+}
+/**
+ * Pre-install the edge signer into a version-pinned, connector-managed
+ * directory and write a stable wrapper that launches it with an absolute Node
+ * path. The signer MCP is then registered as `command: <wrapper>` instead of a
+ * runtime `npx -y @haven_ai/signer@…` invocation.
+ *
+ * Why: launching the signer via bare `npx` at every MCP spawn made it depend on
+ * the PATH/environment the agent runtime hands the stdio subprocess, which is
+ * not the user's interactive shell — the failure mode that left `haven-signer`
+ * stuck at "Failed to connect" while the hosted HTTP server connected fine. The
+ * local MCP topology already avoids this with the same pre-install + wrapper
+ * pattern (see prepareLocalMcpRuntime); this brings the default hosted+signer
+ * topology to parity. Version stays pinned (no unpinned `npm i -g`), and the
+ * wrapper lives under ~/.haven so the reset flow already cleans it up.
+ */
+declare function prepareSignerRuntime(input: PrepareSignerRuntimeInput, deps?: SignerRuntimeDeps): Promise<PreparedSignerRuntime>;
+
+interface RuntimeInstallInput {
+    runtime?: string;
+    hostedMcpUrl: string;
+    apiKey: string;
+    signerPath: string;
+    identityPath: string;
+    credentialDirectory: string;
+    environmentLabel?: string;
+    ackSigner?: boolean;
+    ackLocalTools?: boolean;
+    /**
+     * Explicit opt-in to the local-stdio MCP topology (zero hosted dependency).
+     * Default is hosted MCP + local signer for every runtime; local MCP is only
+     * used when this is true and the runtime supports it.
+     */
+    localMcp?: boolean;
+    /**
+     * #1695: wiring slug for a NAMED MCP pair (haven-<slug> /
+     * haven-signer-<slug>). Absent = the bare pair, unchanged from today.
+     */
+    serverName?: string;
+}
+interface RuntimeInstallResult {
+    runtime: RuntimeId;
+    runtimeMcpMode: RuntimeMcpMode;
+    hostedMcpConfigured: boolean;
+    localSignerConfigured: boolean;
+    localMcpConfigured: boolean;
+    probeResult: string;
+    restartRequired: boolean;
+    nextUserAction: string;
+    errorCode?: string;
+    configTarget?: string;
+    runtimeVersion?: string;
+    signerAcknowledged?: boolean;
+    localMcpAcknowledged?: boolean;
+    activationCommand?: string;
+    skillInstalled?: boolean;
+    /**
+     * Hosted topology only: true when the signer was pre-installed and registered
+     * via its absolute wrapper, false when prep failed and it fell back to the
+     * fragile runtime-`npx` launch. Undefined for local/manual topologies that
+     * do not run the signer as a separate MCP. Lets callers/tests detect the
+     * silent npx fallback instead of treating every write as fully healthy.
+     */
+    signerRuntimePrepared?: boolean;
+    messages: string[];
+}
+/**
+ * The config-write snapshot handed to `onRuntimeConfigured` (#1543). The
+ * booleans mirror the semantics of the FINAL report's unlock keys minus the
+ * probe verdicts: "configured" here means the config write succeeded, the
+ * required consent is acknowledged, and the signer credential exists on disk
+ * (a local fs check) — not that a handshake has verified it. A later probe
+ * failure refines the final report and sets its errorCode; the dashboard's
+ * unlock condition accepts either state.
+ */
+interface EarlyRuntimeConfigReport {
+    runtime: RuntimeId;
+    runtimeMcpMode: RuntimeMcpMode;
+    hostedMcpConfigured: boolean;
+    localSignerConfigured: boolean;
+    localMcpConfigured: boolean;
+    signerAcknowledged?: boolean;
+    localMcpAcknowledged?: boolean;
+    restartRequired: boolean;
+    nextUserAction: string;
+    errorCode?: string;
+}
+interface RuntimeInstallDeps {
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+    fetch?: typeof fetch;
+    /**
+     * Optional live progress callback. installRuntime's slowest steps (signer
+     * pre-install, runtime config write, MCP handshake probes) otherwise emit
+     * nothing until the caller flushes the collected `messages` after this
+     * returns — leaving the console silent through the longest part of setup.
+     * When provided, a few lightweight heartbeat lines are emitted as they run.
+     */
+    onProgress?: (message: string) => void;
+    /**
+     * #1543: invoked once, the moment the runtime MCP config write has settled —
+     * BEFORE the network probes and the skill install. The dashboard withholds
+     * its budget-approval controls until an install-status report shows the
+     * runtime configured, and the final report only lands after the entire
+     * install; gating approval on that tail made the user wait on work approval
+     * does not depend on. The snapshot carries the config-write facts (no probe
+     * verdicts, no skill state); the caller's complete report remains
+     * authoritative and overwrites these keys. Best-effort by contract: a
+     * throwing callback is swallowed and never fails the install.
+     */
+    onRuntimeConfigured?: (report: EarlyRuntimeConfigReport) => Promise<void> | void;
+    runCommand?: (command: string, args: string[]) => Promise<void>;
+    prepareLocalMcpRuntime?: (input: PrepareLocalMcpRuntimeInput) => Promise<PreparedLocalMcpRuntime>;
+    prepareSignerRuntime?: (input: PrepareSignerRuntimeInput) => Promise<PreparedSignerRuntime>;
+    probeSignerTools?: (command: string, args: string[], requiredTools: readonly string[]) => Promise<LocalMcpProbeResult>;
+    probeLocalMcpTools?: (command: string, args: string[], requiredTools: readonly string[]) => Promise<LocalMcpProbeResult>;
+}
+declare function installRuntime(input: RuntimeInstallInput, deps?: RuntimeInstallDeps): Promise<RuntimeInstallResult>;
+declare function runtimeInstallCapabilities(runtime: string | undefined, env?: NodeJS.ProcessEnv): {
+    canWriteRuntimeConfig: boolean;
+    restartRequired: boolean;
+};
+
+/**
+ * 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.0.0-dev.202609031523.fd49e1a";
+interface ConnectOptions {
+    setupToken: string;
+    apiBaseUrl: string;
+    runtime?: string;
+    /** #1672 escape hatch: use exactly this runtime, ignoring environment detection. */
+    runtimeForce?: string;
+    /**
+     * #1719: the harness an AGENT running this command reported for itself. Enters
+     * at the same precedence as `runtime`, so it can only fill a vacuum — never
+     * override a detected environment.
+     */
+    runtimeSelfReport?: string;
+    /**
+     * #1719: this run may ask a human which installed client to configure. The
+     * CLI sets it for a non-`--json` run; a library caller must opt in. Combined
+     * with `deps.isTty`, it is what makes the prompt rung SKIPPED rather than
+     * answered in CI, in `--json` automation, and in library embeddings.
+     */
+    interactive?: boolean;
+    credentialsDir?: string;
+    environmentLabel?: string;
+    /** #1696: wiring slug for a named MCP pair + slug-keyed credential dir. */
+    serverName?: string;
+    connectorVersion?: string;
+    ackSigner?: boolean;
+    ackLocalTools?: boolean;
+    localMcp?: boolean;
+    /**
+     * #1377 D: keep the process alive after registering and poll for the
+     * user's budget approval (default). Set false for structured/automation
+     * runs (--json) where prompt output emission matters more than narration.
+     */
+    waitForApproval?: boolean;
+    /** Test/injection overrides for the approval poll cadence and clock. */
+    approvalWait?: ApprovalWaitOptions;
+}
+/** The stable machine-readable result emitted by `haven-connect --json`. */
+declare const CONNECT_OUTCOME_SCHEMA_VERSION: 1;
+type ConnectOutcomeStatus = 'complete' | 'action_required' | 'failed';
+interface ConnectOutcome {
+    schema_version: typeof CONNECT_OUTCOME_SCHEMA_VERSION;
+    outcome: ConnectOutcomeStatus;
+    runtime: string;
+    topology: string;
+    configuration: {
+        hosted_mcp: boolean;
+        local_signer: boolean;
+        local_mcp: boolean;
+    };
+    probe: {
+        result: string;
+    };
+    activation: {
+        restart_required: boolean;
+        instruction: string;
+    };
+    next_action: string;
+    approval: {
+        required: boolean;
+        expires_at: string | null;
+    };
+    verification: {
+        tools: readonly ['haven_get_agent', 'haven_get_allowances'];
+        instruction: string;
+    };
+    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 {
+    api?: ConnectApiClient;
+    generateKey?: () => LocalDelegateKey;
+    generateApiKey?: () => string;
+    preflightStorage?: typeof preflightCredentialStorage;
+    writeCredentials?: typeof writeCredentialFiles;
+    installRuntime?: typeof installRuntime;
+    log?: (message: string) => void;
+    /** JSON CLI mode must not expose owner-only credential file locations. */
+    redactPaths?: boolean;
+    /** Overridable so the Node-floor refusal is testable without spawning a Node. */
+    nodeVersion?: string;
+    /** Overridable so runtime detection (#1672) is testable without faking process.env. */
+    env?: NodeJS.ProcessEnv;
+    /** Overridable so the #1719 TTY gate is testable without faking process.stdin. */
+    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;
+    agentId: string;
+    delegateAddress: string;
+    credentialPaths: StoredCredentialPaths;
+    /** 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;
+/**
+ * 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;
+/**
+ * #1377 D: after registering, the connector no longer goes dead while the
+ * user approves in Haven — it polls the narrow connector-status endpoint
+ * (agent-API-key auth, works during `setup_pending`) and narrates progress in
+ * the flow's voice, ending in a concrete celebration naming the granted
+ * authority. Bounds (stated per the issue): poll every 5 s, give up after
+ * 3 minutes (36 polls; with the immediate first check below the last one
+ * lands at ~175 s) — the connector ALWAYS terminates on its own; a timeout
+ * is a clean exit with guidance, never a hang. Injectable clock/cadence for
+ * tests.
+ *
+ * #1542: the first check happens BEFORE the "waiting for you to approve" line
+ * is printed. Users routinely approve in the dashboard while the runtime
+ * install is still running, and announcing a wait that is already over made
+ * the very next line ("Budget approved 🎉") read as a contradiction — the
+ * field-test agent relayed the pair verbatim as a bug.
+ */
+interface ApprovalWaitOptions {
+    intervalMs?: number;
+    timeoutMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+
+interface ParsedCli {
+    options: ConnectOptions;
+    help: boolean;
+    json: boolean;
+    /** #1589: diagnosis mode — no setup token required. */
+    doctor: boolean;
+    repair: boolean;
+    /** #1681: retire an agent credential directory in place — no token required. */
+    tombstone?: {
+        directory: string;
+        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
+     * address, `finish` writes the key the owner brings back. No setup token: the
+     * re-key API is owner-authenticated and this connector never calls it.
+     */
+    rekey?: {
+        phase: 'start' | 'finish';
+        newApiKey?: string;
+    };
+}
+declare function parseArgs(argv: string[], env?: NodeJS.ProcessEnv): ParsedCli;
+declare function helpText(): string;
+
+declare function redactSecrets(value: string): string;
+declare function shortAddress(address: string): string;
+
+/**
+ * The connector's machine-readable failure vocabulary (#1719).
+ *
+ * Before this, a refusal was a bare `throw new Error(...)` and the automation
+ * contract recovered a code by regex-matching the message in
+ * `failedConnectOutcome`. That works only for as long as nobody rewords a
+ * sentence, and it gives the caller nothing to branch on that the wording did
+ * not accidentally provide. Every refusal this module fronts carries:
+ *
+ * - `code` — stable, snake_case, safe to switch on;
+ * - `nextAction` — the one thing to do next, in the same snake_case shape the
+ *   install-status contract already uses for `next_action`;
+ * - `message` — human/agent prose, still the thing printed to a terminal.
+ *
+ * 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;
+    readonly details: ConnectErrorDetails;
+    constructor(code: string, message: string, nextAction: string, details?: ConnectErrorDetails);
+}
+declare function isConnectError(err: unknown): err is ConnectError;
+
+declare const MCP_RUNTIME_MANIFEST: {
+    readonly mcpPackage: "@haven_ai/mcp";
+    readonly mcpVersion: "0.0.0-dev.202609031523.fd49e1a";
+    readonly sdkPackage: "@haven_ai/sdk";
+    readonly sdkVersion: "0.0.0-dev.202609031523.fd49e1a";
+    readonly signerPackage: "@haven_ai/signer";
+    readonly signerVersion: "0.0.0-dev.202609031523.fd49e1a";
+    readonly minimumNodeVersion: "22.0.0";
+    readonly supportedClients: readonly ["codex-cli", "codex-desktop", "claude-code"];
+    readonly requiredTools: readonly string[];
+    /**
+     * The signer MCP's tool surface, DERIVED from the pinned @haven_ai/signer
+     * package (#1587) — same anti-drift rule as `requiredTools` above: a
+     * literal list here would rot the first time the signer gains a tool.
+     * The handshake probe requires all of them.
+     */
+    readonly requiredSignerTools: readonly string[];
+};
+declare function mcpPackageSpec(): string;
+declare function sdkPackageSpec(): string;
+declare function signerPackageSpec(): string;
+
+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 };