@haven_ai/connect 0.8.1-alpha.0 → 0.10.0-alpha.0

package/dist/index.d.cts

@@ -17,6 +17,21 @@ interface ConnectApiClient {
      * of the dashboard hand-off — see {@link AgentIdentity}.
      */
     getAgentIdentity(apiKey: string): Promise<AgentIdentity>;
+    /**
+     * #3772: tell Haven which agents this run's `--replace` retired locally, so
+     * their own reads can warn a still-running session. Authenticated with the
+     * NEW agent's key. `null` when the backend predates the route (404); any
+     * other failure throws for the caller to log. Warning-only on the backend:
+     * nothing is paused or revoked.
+     */
+    reportRetiredAgents?(input: ReportRetiredAgentsInput): Promise<{
+        recordedAgentIds: string[];
+    } | null>;
+}
+interface ReportRetiredAgentsInput {
+    setupId: string;
+    apiKey: string;
+    retiredAgentIds: readonly string[];
 }
 interface ConnectorStatusResponse {
     status: string;
@@ -86,8 +101,9 @@ interface UpdateInstallStatusInput {
     errorCode?: string | null;
     environmentLabel?: string;
     /**
-     * The other agent directories this machine holds, so the DASHBOARD can offer
-     * the owner a one-click revoke of what this setup superseded (#2561).
+     * The other agent directories this machine holds, so the DASHBOARD can list
+     * them for the owner (#2561). Every other directory, not a replace set: the
+     * dashboard calls none of them replaced and offers no revoke (#3830).
      *
      * A tri-state, and the middle case is why it is not a plain array:
      *
@@ -237,6 +253,19 @@ interface PreflightCredentialStorageInput {
 }
 declare function preflightCredentialStorage(input?: PreflightCredentialStorageInput): Promise<string>;
 declare function writeCredentialFiles(input: WriteCredentialInput): Promise<StoredCredentialPaths>;
+interface ResolveAgentDirectoryOptions {
+    /** The credential ROOT to scan. Default: ~/.haven/agents. */
+    root?: string;
+    /**
+     * Retired (tombstoned) directories may claim a slug. Only --unwire wants
+     * this: it must reach a retired agent to release its name. Selection for
+     * --doctor/--repair/--rekey never matches a tombstoned directory.
+     */
+    allowRetired?: boolean;
+}
+/** Does THIS directory record the pair for `slug`? Shared agree-check for `--name` + `--credentials-dir`. */
+declare function assertDirectoryRecordsSlug(directory: string, slug: string): Promise<void>;
+declare function resolveAgentDirectoryBySlug(slug: string, opts?: ResolveAgentDirectoryOptions): Promise<string>;
 declare function defaultAgentDirectory(agentId: string, baseDir?: string): string;
 /**
  * Where the terminal `ConnectOutcome` is parked so a caller that lost the
@@ -652,6 +681,14 @@ interface InstalledClientCandidate {
      * whether that file exists today.
      */
     configPath: string | null;
+    /**
+     * The file the config-file evidence was found in, when this candidate
+     * carries that tier. Usually the same file `configPath` names — except for
+     * Claude Code, whose evidence lives in `~/.claude.json` while `configPath`
+     * stays `null` (the connector would configure it through its own CLI, not
+     * by writing a file it owns).
+     */
+    evidencePath?: string | null;
     evidence: 'config-file' | 'client-directory';
 }
 interface ScanInstalledClientsOptions {
@@ -661,6 +698,8 @@ interface ScanInstalledClientsOptions {
     env?: NodeJS.ProcessEnv;
     /** Injectable so the scan is testable without a populated home directory. */
     exists?: (path: string) => Promise<boolean>;
+    /** Injectable so the `mcpServers` evidence check is testable without a real file. */
+    readFile?: (path: string) => Promise<string>;
 }
 declare function scanInstalledClients(options?: ScanInstalledClientsOptions): Promise<InstalledClientCandidate[]>;
 /**
@@ -743,7 +782,7 @@ type WiringCollisionResolution = {
     action: 'abort';
 };
 
-declare const CONNECTOR_VERSION = "0.8.1-alpha.0";
+declare const CONNECTOR_VERSION = "0.10.0-alpha.0";
 interface ConnectOptions {
     setupToken: string;
     apiBaseUrl: string;
@@ -767,6 +806,19 @@ interface ConnectOptions {
     environmentLabel?: string;
     /** #1696: wiring slug for a named MCP pair + slug-keyed credential dir. */
     serverName?: string;
+    /**
+     * #3737: derive the wiring slug from the agent's display name and install
+     * a NAMED pair (`haven-<slug>` / `haven-signer-<slug>`) instead of the bare
+     * one. The CLI passes this by default so that adding an agent never
+     * targets the bare pair and therefore never has to ask replace-vs-
+     * alongside; the LIBRARY keeps today's bare behaviour when neither
+     * `serverName` nor this option is set, so existing programmatic callers
+     * are unchanged. An explicit `serverName` always wins over derivation.
+     * The derived slug de-collides against EVERY directory name under the
+     * credential root, marks non-production backends with a `-dev` suffix
+     * (owner decision 4), and is refused nothing — it never displaces anyone.
+     */
+    deriveServerName?: boolean;
     /**
      * #2551: when the bare pair on this machine is already wired to a different
      * agent with a live key, replace it — re-point `haven` / `haven-signer` at
@@ -927,6 +979,16 @@ interface ConnectOutcome {
         bound_at: string;
         backend_changed: boolean;
     };
+    /**
+     * #3737, additive within schema_version 1: the hosted MCP server name this
+     * run actually wired — `haven-<slug>` for a named run (derived or
+     * explicit), bare `haven` for a `--bare` / `--replace` run. The mirror of
+     * what `mcpServerName` reported to the backend at register and what the
+     * completion text names, carried structurally so a `--json` caller can
+     * verify `hermes mcp test <name>` without parsing prose. Always present on
+     * a completed run; absent on `failedConnectOutcome`, which wired nothing.
+     */
+    server_name?: string;
     /**
      * #2091, additive within schema_version 1: `message` is the redacted human
      * refusal (automation used to get code + next_action and nothing to act
@@ -992,6 +1054,14 @@ interface ConnectDeps {
     isStdoutTty?: boolean;
     /** Overridable so the #1719 installed-client prompt is testable without readline. */
     promptRuntime?: () => Promise<RuntimeId>;
+    /**
+     * Overridable so the DEFAULT prompt thunk is observable: the call site in
+     * `runtimeSelectionPrompt` must pass the hint scan's `env` to it (#3732) —
+     * the prompt rung and the `--json` refusal describe ONE machine, so they
+     * must look at the same environment. Takes the full scan options, env
+     * included; defaults to `resolveRuntimeByInstalledClientPrompt`.
+     */
+    promptRuntimeByInstalledClient?: typeof resolveRuntimeByInstalledClientPrompt;
     /**
      * Overridable so the #2551 replace-vs-alongside prompt is testable without
      * readline. Reached only through the same `interactive` + TTY gate as
@@ -1032,6 +1102,8 @@ declare function completionOutcome(input: {
     runtimeInstall: RuntimeInstallResult;
     delegateAddress: string;
     hostedMcpUrl?: string;
+    /** #3737: the resolved wiring slug; absent means the bare pair. */
+    serverName?: string;
     supersededAgentIds?: readonly string[];
     /** #2551: only a replace run sets these; see the outcome fields' doc comments. */
     supersededAgentsRetiredLocally?: boolean;
@@ -1046,6 +1118,11 @@ declare function completionOutcome(input: {
         account_address: string | null;
     }>;
     serverNameReboundFrom?: ConnectOutcome['server_name_rebound_from'];
+    /** #3772: set only when this run re-pointed wiring another agent held. */
+    staleSession?: {
+        agentIds: readonly string[];
+        otherBackendAgentId?: string;
+    };
 }): ConnectOutcome;
 /**
  * The failure record for the `--json` contract.
@@ -1194,11 +1271,11 @@ declare function isConnectError(err: unknown): err is ConnectError;
 
 declare const MCP_RUNTIME_MANIFEST: {
     readonly mcpPackage: "@haven_ai/mcp";
-    readonly mcpVersion: "0.8.1-alpha.0";
+    readonly mcpVersion: "0.10.0-alpha.0";
     readonly sdkPackage: "@haven_ai/sdk";
-    readonly sdkVersion: "0.8.1-alpha.0";
+    readonly sdkVersion: "0.10.0-alpha.0";
     readonly signerPackage: "@haven_ai/signer";
-    readonly signerVersion: "0.8.1-alpha.0";
+    readonly signerVersion: "0.10.0-alpha.0";
     readonly minimumNodeVersion: "22.0.0";
     readonly supportedClients: readonly ["codex-cli", "codex-desktop", "claude-code"];
     readonly requiredTools: readonly string[];
@@ -1214,4 +1291,4 @@ 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 };
+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 ResolveAgentDirectoryOptions, type ResolveSetupInput, type ResolvedSetup, type RuntimeId, type RuntimeInstallInput, type RuntimeInstallResult, type RuntimeProfile, type RuntimeResolutionOptions, type RuntimeSelection, type ScanInstalledClientsOptions, type StoredCredentialPaths, type UpdateInstallStatusInput, type WriteCredentialInput, assertDirectoryRecordsSlug, completionOutcome, createConnectApiClient, defaultAgentDirectory, delegateKeyFromPrivateKey, failedConnectOutcome, failureOutcomeFor, generateDelegateKey, helpText, installRuntime, installedClientHint, isConnectError, mcpPackageSpec, normalizeRuntime, parseArgs, prepareSignerRuntime, promptForInstalledClient, redactSecrets, resolveAgentDirectoryBySlug, resolveRuntimeByInstalledClientPrompt, resolveRuntimeSelection, runConnect, runtimeInstallCapabilities, runtimeProfile, scanInstalledClients, sdkPackageSpec, shortAddress, signerPackageSpec, writeConnectOutcomeRecord, writeCredentialFiles };

package/dist/index.d.ts

@@ -17,6 +17,21 @@ interface ConnectApiClient {
      * of the dashboard hand-off — see {@link AgentIdentity}.
      */
     getAgentIdentity(apiKey: string): Promise<AgentIdentity>;
+    /**
+     * #3772: tell Haven which agents this run's `--replace` retired locally, so
+     * their own reads can warn a still-running session. Authenticated with the
+     * NEW agent's key. `null` when the backend predates the route (404); any
+     * other failure throws for the caller to log. Warning-only on the backend:
+     * nothing is paused or revoked.
+     */
+    reportRetiredAgents?(input: ReportRetiredAgentsInput): Promise<{
+        recordedAgentIds: string[];
+    } | null>;
+}
+interface ReportRetiredAgentsInput {
+    setupId: string;
+    apiKey: string;
+    retiredAgentIds: readonly string[];
 }
 interface ConnectorStatusResponse {
     status: string;
@@ -86,8 +101,9 @@ interface UpdateInstallStatusInput {
     errorCode?: string | null;
     environmentLabel?: string;
     /**
-     * The other agent directories this machine holds, so the DASHBOARD can offer
-     * the owner a one-click revoke of what this setup superseded (#2561).
+     * The other agent directories this machine holds, so the DASHBOARD can list
+     * them for the owner (#2561). Every other directory, not a replace set: the
+     * dashboard calls none of them replaced and offers no revoke (#3830).
      *
      * A tri-state, and the middle case is why it is not a plain array:
      *
@@ -237,6 +253,19 @@ interface PreflightCredentialStorageInput {
 }
 declare function preflightCredentialStorage(input?: PreflightCredentialStorageInput): Promise<string>;
 declare function writeCredentialFiles(input: WriteCredentialInput): Promise<StoredCredentialPaths>;
+interface ResolveAgentDirectoryOptions {
+    /** The credential ROOT to scan. Default: ~/.haven/agents. */
+    root?: string;
+    /**
+     * Retired (tombstoned) directories may claim a slug. Only --unwire wants
+     * this: it must reach a retired agent to release its name. Selection for
+     * --doctor/--repair/--rekey never matches a tombstoned directory.
+     */
+    allowRetired?: boolean;
+}
+/** Does THIS directory record the pair for `slug`? Shared agree-check for `--name` + `--credentials-dir`. */
+declare function assertDirectoryRecordsSlug(directory: string, slug: string): Promise<void>;
+declare function resolveAgentDirectoryBySlug(slug: string, opts?: ResolveAgentDirectoryOptions): Promise<string>;
 declare function defaultAgentDirectory(agentId: string, baseDir?: string): string;
 /**
  * Where the terminal `ConnectOutcome` is parked so a caller that lost the
@@ -652,6 +681,14 @@ interface InstalledClientCandidate {
      * whether that file exists today.
      */
     configPath: string | null;
+    /**
+     * The file the config-file evidence was found in, when this candidate
+     * carries that tier. Usually the same file `configPath` names — except for
+     * Claude Code, whose evidence lives in `~/.claude.json` while `configPath`
+     * stays `null` (the connector would configure it through its own CLI, not
+     * by writing a file it owns).
+     */
+    evidencePath?: string | null;
     evidence: 'config-file' | 'client-directory';
 }
 interface ScanInstalledClientsOptions {
@@ -661,6 +698,8 @@ interface ScanInstalledClientsOptions {
     env?: NodeJS.ProcessEnv;
     /** Injectable so the scan is testable without a populated home directory. */
     exists?: (path: string) => Promise<boolean>;
+    /** Injectable so the `mcpServers` evidence check is testable without a real file. */
+    readFile?: (path: string) => Promise<string>;
 }
 declare function scanInstalledClients(options?: ScanInstalledClientsOptions): Promise<InstalledClientCandidate[]>;
 /**
@@ -743,7 +782,7 @@ type WiringCollisionResolution = {
     action: 'abort';
 };
 
-declare const CONNECTOR_VERSION = "0.8.1-alpha.0";
+declare const CONNECTOR_VERSION = "0.10.0-alpha.0";
 interface ConnectOptions {
     setupToken: string;
     apiBaseUrl: string;
@@ -767,6 +806,19 @@ interface ConnectOptions {
     environmentLabel?: string;
     /** #1696: wiring slug for a named MCP pair + slug-keyed credential dir. */
     serverName?: string;
+    /**
+     * #3737: derive the wiring slug from the agent's display name and install
+     * a NAMED pair (`haven-<slug>` / `haven-signer-<slug>`) instead of the bare
+     * one. The CLI passes this by default so that adding an agent never
+     * targets the bare pair and therefore never has to ask replace-vs-
+     * alongside; the LIBRARY keeps today's bare behaviour when neither
+     * `serverName` nor this option is set, so existing programmatic callers
+     * are unchanged. An explicit `serverName` always wins over derivation.
+     * The derived slug de-collides against EVERY directory name under the
+     * credential root, marks non-production backends with a `-dev` suffix
+     * (owner decision 4), and is refused nothing — it never displaces anyone.
+     */
+    deriveServerName?: boolean;
     /**
      * #2551: when the bare pair on this machine is already wired to a different
      * agent with a live key, replace it — re-point `haven` / `haven-signer` at
@@ -927,6 +979,16 @@ interface ConnectOutcome {
         bound_at: string;
         backend_changed: boolean;
     };
+    /**
+     * #3737, additive within schema_version 1: the hosted MCP server name this
+     * run actually wired — `haven-<slug>` for a named run (derived or
+     * explicit), bare `haven` for a `--bare` / `--replace` run. The mirror of
+     * what `mcpServerName` reported to the backend at register and what the
+     * completion text names, carried structurally so a `--json` caller can
+     * verify `hermes mcp test <name>` without parsing prose. Always present on
+     * a completed run; absent on `failedConnectOutcome`, which wired nothing.
+     */
+    server_name?: string;
     /**
      * #2091, additive within schema_version 1: `message` is the redacted human
      * refusal (automation used to get code + next_action and nothing to act
@@ -992,6 +1054,14 @@ interface ConnectDeps {
     isStdoutTty?: boolean;
     /** Overridable so the #1719 installed-client prompt is testable without readline. */
     promptRuntime?: () => Promise<RuntimeId>;
+    /**
+     * Overridable so the DEFAULT prompt thunk is observable: the call site in
+     * `runtimeSelectionPrompt` must pass the hint scan's `env` to it (#3732) —
+     * the prompt rung and the `--json` refusal describe ONE machine, so they
+     * must look at the same environment. Takes the full scan options, env
+     * included; defaults to `resolveRuntimeByInstalledClientPrompt`.
+     */
+    promptRuntimeByInstalledClient?: typeof resolveRuntimeByInstalledClientPrompt;
     /**
      * Overridable so the #2551 replace-vs-alongside prompt is testable without
      * readline. Reached only through the same `interactive` + TTY gate as
@@ -1032,6 +1102,8 @@ declare function completionOutcome(input: {
     runtimeInstall: RuntimeInstallResult;
     delegateAddress: string;
     hostedMcpUrl?: string;
+    /** #3737: the resolved wiring slug; absent means the bare pair. */
+    serverName?: string;
     supersededAgentIds?: readonly string[];
     /** #2551: only a replace run sets these; see the outcome fields' doc comments. */
     supersededAgentsRetiredLocally?: boolean;
@@ -1046,6 +1118,11 @@ declare function completionOutcome(input: {
         account_address: string | null;
     }>;
     serverNameReboundFrom?: ConnectOutcome['server_name_rebound_from'];
+    /** #3772: set only when this run re-pointed wiring another agent held. */
+    staleSession?: {
+        agentIds: readonly string[];
+        otherBackendAgentId?: string;
+    };
 }): ConnectOutcome;
 /**
  * The failure record for the `--json` contract.
@@ -1194,11 +1271,11 @@ declare function isConnectError(err: unknown): err is ConnectError;
 
 declare const MCP_RUNTIME_MANIFEST: {
     readonly mcpPackage: "@haven_ai/mcp";
-    readonly mcpVersion: "0.8.1-alpha.0";
+    readonly mcpVersion: "0.10.0-alpha.0";
     readonly sdkPackage: "@haven_ai/sdk";
-    readonly sdkVersion: "0.8.1-alpha.0";
+    readonly sdkVersion: "0.10.0-alpha.0";
     readonly signerPackage: "@haven_ai/signer";
-    readonly signerVersion: "0.8.1-alpha.0";
+    readonly signerVersion: "0.10.0-alpha.0";
     readonly minimumNodeVersion: "22.0.0";
     readonly supportedClients: readonly ["codex-cli", "codex-desktop", "claude-code"];
     readonly requiredTools: readonly string[];
@@ -1214,4 +1291,4 @@ 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 };
+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 ResolveAgentDirectoryOptions, type ResolveSetupInput, type ResolvedSetup, type RuntimeId, type RuntimeInstallInput, type RuntimeInstallResult, type RuntimeProfile, type RuntimeResolutionOptions, type RuntimeSelection, type ScanInstalledClientsOptions, type StoredCredentialPaths, type UpdateInstallStatusInput, type WriteCredentialInput, assertDirectoryRecordsSlug, completionOutcome, createConnectApiClient, defaultAgentDirectory, delegateKeyFromPrivateKey, failedConnectOutcome, failureOutcomeFor, generateDelegateKey, helpText, installRuntime, installedClientHint, isConnectError, mcpPackageSpec, normalizeRuntime, parseArgs, prepareSignerRuntime, promptForInstalledClient, redactSecrets, resolveAgentDirectoryBySlug, resolveRuntimeByInstalledClientPrompt, resolveRuntimeSelection, runConnect, runtimeInstallCapabilities, runtimeProfile, scanInstalledClients, sdkPackageSpec, shortAddress, signerPackageSpec, writeConnectOutcomeRecord, writeCredentialFiles };