@haven_ai/connect 0.1.34-alpha.0 → 0.1.35-alpha.0

package/dist/index.d.cts

@@ -50,6 +50,14 @@ interface RegisterSetupInput extends ResolveSetupInput {
      * of those may render as unknown.
      */
     mcpServerName?: string;
+    /**
+     * #2528: how this run was invoked — `'json'` when `--json` was passed,
+     * `'prose'` otherwise. The connector is the only party that can report it:
+     * the register call is byte-identical over the wire either way, so there is
+     * no header, user agent or timing signal the backend could recover it from.
+     * Optional on the wire so an older backend simply ignores it.
+     */
+    runMode?: 'json' | 'prose';
     connectorContext?: ConnectorContext;
     installCapabilities?: {
         canWriteRuntimeConfig?: boolean;
@@ -77,6 +85,25 @@ interface UpdateInstallStatusInput {
     nextUserAction: string;
     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).
+     *
+     * A tri-state, and the middle case is why it is not a plain array:
+     *
+     * - a list  — the scan ran and found these;
+     * - `[]`    — the scan ran and found none;
+     * - `null` or absent — the scan could not run.
+     *
+     * The connector cannot revoke and must not: `POST /agents/:id/revoke` is
+     * owner-authenticated, and an agent credential retiring a sibling agent is
+     * the "agent editing its own authority" the re-key routes already refuse.
+     * So this reports, and a human clicks.
+     *
+     * `null` matters because the alternative is a dashboard telling somebody
+     * "nothing to revoke" about a machine nobody managed to read.
+     */
+    supersededAgentIds?: readonly string[] | null;
 }
 interface ConnectorContext {
     environment_label?: string;
@@ -121,6 +148,13 @@ interface RegisterSetupResponse {
     delegate_address: string;
     hosted_mcp_url: string;
     next_action: string;
+    /**
+     * #2528: the absolute link that lands the user on this setup's budget
+     * approval. Optional because a backend older than #2528 does not send it,
+     * and the connector must degrade to its previous prose rather than print
+     * `undefined` — see `approvalCtaLine`.
+     */
+    approval_url?: string;
 }
 /**
  * The agent identity behind an API key (#1700).
@@ -271,7 +305,7 @@ interface RuntimeResolutionOptions {
 /**
  * Runtime resolution, detection-first (#1672) and self-resolving (#1719).
  *
- * The setup command carries no `--runtime`; the connector works out the
+ * The connector command carries no `--runtime`; the connector works out the
  * runtime it is executing inside. Precedence:
  *
  * 1. `--runtime-force <name>` — always wins (unknown name refuses).
@@ -314,6 +348,94 @@ interface LocalMcpProbeResult {
     toolNames?: string[];
 }
 
+/**
+ * Local runtime-spec override (#2424, slice 4 of epic #2420).
+ *
+ * `prepareSignerRuntime` and `prepareLocalMcpRuntime` install the connector's
+ * PINNED siblings — `@haven_ai/signer@<pin>`, `@haven_ai/sdk@<pin>`,
+ * `@haven_ai/mcp@<pin>` from `runtime-manifest.ts` — into a version-named
+ * directory under `~/.haven`. That is right for every user and wrong for the
+ * one developer iterating on the signer or SDK, who until now had to publish
+ * to find out whether a change works end to end.
+ *
+ * Three environment variables let that developer name a different spec:
+ *
+ *   HAVEN_SIGNER_SPEC   what `npm install` gets instead of `@haven_ai/signer@<pin>`
+ *   HAVEN_SDK_SPEC      … instead of `@haven_ai/sdk@<pin>`
+ *   HAVEN_MCP_SPEC      … instead of `@haven_ai/mcp@<pin>` (the `--local` topology)
+ *
+ * A value is anything `npm install` accepts as a package spec whose name is
+ * fixed by the variable: `file:/abs/path/to/packages/signer`, a `.tgz` from
+ * `npm pack`, or an explicit version such as `@haven_ai/signer@0.0.0-dev.…`.
+ *
+ * ## Why environment variables and not a `--runtime-spec` flag
+ *
+ * - The install runs from THREE entry points — `--setup`, `--doctor --repair`
+ *   and `--rekey-finish` — and every one of them has to honour the same
+ *   override or the developer's re-key silently reinstalls the registry build.
+ *   One env read inside the two `prepare*Runtime` functions covers all three;
+ *   a flag would have to be plumbed through each argv parser and each result
+ *   type separately, and the first one forgotten is a hole.
+ * - The connector command is minted by the dashboard and pasted verbatim, often by
+ *   an agent. An override that lived in argv would have to be spliced into a
+ *   command the developer did not write; an env var sits beside it.
+ * - It is out of band by construction: an agent following the printed command
+ *   cannot pass it by accident, and it never appears in the copy-pasted line.
+ * - It matches the vocabulary the backend already uses for the same axis
+ *   (`HAVEN_CONNECTOR_CHANNEL`, #2422/#2423).
+ *
+ * ## What an active override changes, and what it never changes
+ *
+ * - The runtime directory is keyed by a short hash of the RESOLVED specs
+ *   (`override-<hash>`) instead of the manifest version, so an override can
+ *   never poison the pinned directory the normal path reuses.
+ * - An override install is never reused from an earlier run: a rebuilt local
+ *   package must not be shadowed by a cache hit, and `npm install` of an
+ *   already-satisfied spec is cheap.
+ * - The override is printed loudly in setup output, recorded in the sidecar,
+ *   written as a comment into the wrapper the agent client launches, and
+ *   reported by `--doctor` as a failing check.
+ * - The post-setup handshake probe still requires every tool in
+ *   `requiredTools` / `requiredSignerTools`, so a local build that dropped a
+ *   tool fails setup exactly like a bad registry version would.
+ * - No variable set → nothing here runs. `resolveRuntimeSpecOverride` returns
+ *   `undefined`, the callers fall through to the manifest specs, and the
+ *   install args, directory, sidecar and wrapper are byte-for-byte what they
+ *   were before this module existed. `signer-runtime.test.ts` pins that.
+ *
+ * ## Validation
+ *
+ * A set-but-malformed value is refused BEFORE `npm` is invoked, naming the
+ * variable: empty or whitespace-only, containing whitespace or a control
+ * character, or containing a shell metacharacter. The install runs through
+ * `execFile` (no shell), so a metacharacter could not inject anything — the
+ * refusal is because such a value is almost never a spec npm would accept, and
+ * when it is not, the failure would otherwise surface minutes later as an npm
+ * error that does not name the variable. The one legitimate casualty is a
+ * `file:` path whose segments contain `*`, `[`, `]`, `{` or `}` — legal in a
+ * filesystem name, refused here on purpose: the check fails closed, the
+ * message names the variable, and a developer can rename the checkout.
+ */
+declare const RUNTIME_SPEC_ENV: {
+    readonly signer: "HAVEN_SIGNER_SPEC";
+    readonly sdk: "HAVEN_SDK_SPEC";
+    readonly mcp: "HAVEN_MCP_SPEC";
+};
+type RuntimeSpecPackage = keyof typeof RUNTIME_SPEC_ENV;
+/** Every override that is set — absent keys mean "the pinned manifest spec". */
+type RuntimeSpecOverride = Partial<Record<RuntimeSpecPackage, string>>;
+/**
+ * The record written into the runtime sidecar and read back by `--doctor`.
+ * `specs` holds only the overridden packages; `resolved_specs` holds every
+ * spec the install actually ran with, overridden or pinned, in the order the
+ * directory key hashes them.
+ */
+interface RuntimeSpecOverrideRecord {
+    specs: RuntimeSpecOverride;
+    resolved_specs: string[];
+    directory_key: string;
+}
+
 interface PrepareLocalMcpRuntimeInput {
     credentialDirectory: string;
     identityPath: string;
@@ -331,6 +453,8 @@ interface PreparedLocalMcpRuntime {
     npmCacheDirectory: string;
     cliPath: string;
     messages: string[];
+    /** #2424: present only when the install ran under a runtime-spec override. */
+    runtimeSpecOverride?: RuntimeSpecOverrideRecord;
 }
 
 interface PrepareSignerRuntimeInput {
@@ -350,11 +474,19 @@ interface PreparedSignerRuntime {
     npmCacheDirectory: string;
     cliPath: string;
     messages: string[];
+    /** #2424: present only when the install ran under a runtime-spec override. */
+    runtimeSpecOverride?: RuntimeSpecOverrideRecord;
 }
 interface SignerRuntimeDeps {
     runCommand?: (command: string, args: string[]) => Promise<void>;
     /** Heartbeats during the (possibly minutes-long) npm install (#1586). */
     onProgress?: (message: string) => void;
+    /**
+     * #2424: where `HAVEN_SIGNER_SPEC` / `HAVEN_SDK_SPEC` are read from.
+     * Defaults to `process.env`; injected so tests can prove both that an
+     * override is honoured and that its absence changes nothing.
+     */
+    env?: NodeJS.ProcessEnv;
 }
 /**
  * Pre-install the edge signer into a version-pinned, connector-managed
@@ -573,7 +705,31 @@ declare function resolveRuntimeByInstalledClientPrompt(options?: ScanInstalledCl
     io?: PromptIo;
 }): Promise<RuntimeId>;
 
-declare const CONNECTOR_VERSION = "0.1.34-alpha.0";
+interface SupersededDirectory {
+    directory: string;
+    /** Agent id from `identity.json`, or the directory name when it is missing. */
+    agentId: string;
+}
+interface WiringCollision {
+    /** Every bare-pair directory holding a usable key — what this run would displace. */
+    superseded: readonly SupersededDirectory[];
+    /**
+     * A valid, collision-checked slug the user can take to install alongside
+     * instead. Derived from the agent name Haven resolved for this setup, so
+     * the proposal reads as the agent rather than as a counter.
+     */
+    suggestedServerName: string;
+}
+type WiringCollisionResolution = {
+    action: 'replace';
+} | {
+    action: 'alongside';
+    serverName: string;
+} | {
+    action: 'abort';
+};
+
+declare const CONNECTOR_VERSION = "0.1.35-alpha.0";
 interface ConnectOptions {
     setupToken: string;
     apiBaseUrl: string;
@@ -597,18 +753,43 @@ interface ConnectOptions {
     environmentLabel?: string;
     /** #1696: wiring slug for a named MCP pair + slug-keyed credential dir. */
     serverName?: string;
+    /**
+     * #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
+     * the new agent (the #1569 remove-first install) and retire the superseded
+     * directory locally afterwards. Without it, such a collision is put to a
+     * human at a TTY and REFUSED everywhere else (`wiring_collision`), before
+     * anything is minted or written. Contradicts `serverName`, which installs
+     * alongside instead; the CLI refuses the pair.
+     */
+    replaceExistingWiring?: boolean;
     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.
+     * user's budget approval. Set false for structured/automation runs (--json)
+     * where prompt output emission matters more than narration. #2484: when
+     * UNSPECIFIED (the default), the wait runs only when stdout is a TTY — the
+     * wait exists to narrate to a watching human, and a prose run whose stdout
+     * is not a TTY (an agent tool call) skips it. An explicit true waits
+     * regardless of TTY.
      */
     waitForApproval?: boolean;
     /** Test/injection overrides for the approval poll cadence and clock. */
     approvalWait?: ApprovalWaitOptions;
+    /**
+     * #2528: how this run was invoked, reported to the backend at register so
+     * the onboarding funnel can segment machine-readable runs from narrated
+     * ones (D1, #2529).
+     *
+     * An explicit option rather than an inference from `waitForApproval`: that
+     * flag is already false for a prose run with no TTY (#2484) and can be set
+     * false by hand, so reading `--json` off it would mislabel real prose runs.
+     * Defaults to `'prose'` — the mode a caller who says nothing is in.
+     */
+    runMode?: 'json' | 'prose';
 }
 /** The stable machine-readable result emitted by `haven-connect --json`. */
 declare const CONNECT_OUTCOME_SCHEMA_VERSION: 1;
@@ -631,9 +812,19 @@ interface ConnectOutcome {
         instruction: string;
     };
     next_action: string;
+    /**
+     * `url` is #2528, additive within schema_version 1 — the same convention
+     * #2173, #2174, #2551, #2091 and #2279 followed for this object. Present
+     * only when the backend returned one: a deployment older than #2528 sends
+     * nothing, and a key whose value is `undefined` disappears from
+     * `JSON.stringify` anyway, so a consumer must test for it rather than
+     * assume it. `required: false` runs carry no url — there is nothing to
+     * approve.
+     */
     approval: {
         required: boolean;
         expires_at: string | null;
+        url?: string;
     };
     verification: {
         tools: readonly ['haven_get_agent', 'haven_get_allowances'];
@@ -664,6 +855,25 @@ interface ConnectOutcome {
      */
     hosted_mcp_url?: string;
     superseded_agent_ids?: readonly string[];
+    /**
+     * #2551, additive within schema_version 1. Present only on a run that
+     * REPLACED existing wiring (`--replace`, or "replace" chosen at the
+     * prompt): `true` when every superseded directory was retired locally —
+     * tombstoned and its local key files removed — and `false` when the
+     * runtime install ended with an errorCode and the retirement was therefore
+     * skipped, because the old wiring may still be the only working one. It
+     * says nothing about the backend: nothing is revoked by the connector.
+     *
+     * `retired_agent_ids` names exactly WHICH directories that retirement
+     * reached — the collision set, and only the members whose tombstone and
+     * teardown both succeeded. It is deliberately a separate list from
+     * `superseded_agent_ids`, which is every OTHER directory on the machine
+     * (#1688) and so also names NAMED agents that coexist with the replaced
+     * bare pair and were never touched; reading the boolean against that list
+     * would overclaim (review finding on #2551).
+     */
+    superseded_agents_retired_locally?: boolean;
+    retired_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
@@ -692,6 +902,15 @@ interface ConnectOutcome {
          */
         installed_clients?: readonly string[];
         suggested_runtime?: string;
+        /**
+         * #2551, additive within schema_version 1, on a `wiring_collision`
+         * refusal: the agents a bare-pair setup would have displaced, and a
+         * valid, collision-checked `--name` the run can be re-issued with. The
+         * refusal is a RELAY instruction — the human chooses replace-vs-alongside
+         * — so the record carries what that human needs, never a default.
+         */
+        superseded_agent_ids?: readonly string[];
+        suggested_name?: string;
     };
 }
 interface ConnectDeps {
@@ -710,8 +929,22 @@ interface ConnectDeps {
     env?: NodeJS.ProcessEnv;
     /** Overridable so the #1719 TTY gate is testable without faking process.stdin. */
     isTty?: boolean;
+    /**
+     * Overridable so the #2484 non-TTY narration gate is testable without
+     * faking process.stdout. Distinct from `isTty`: that gate decides whether
+     * the stdin prompt rung can run (INTERACTIVITY); this one decides whether
+     * the budget-approval wait has a watching human to narrate to, so it is
+     * keyed on STDOUT.
+     */
+    isStdoutTty?: boolean;
     /** Overridable so the #1719 installed-client prompt is testable without readline. */
     promptRuntime?: () => Promise<RuntimeId>;
+    /**
+     * Overridable so the #2551 replace-vs-alongside prompt is testable without
+     * readline. Reached only through the same `interactive` + TTY gate as
+     * `promptRuntime`; a `--json` or piped run never gets here.
+     */
+    promptWiringCollision?: (collision: WiringCollision, agentName: string) => Promise<WiringCollisionResolution>;
     /**
      * Overridable so the #2173 recovery-record write is testable without a real
      * credential directory — and so a FAILING writer can be injected to prove
@@ -747,8 +980,12 @@ declare function completionOutcome(input: {
     delegateAddress: string;
     hostedMcpUrl?: string;
     supersededAgentIds?: readonly string[];
+    /** #2551: only a replace run sets these; see the outcome fields' doc comments. */
+    supersededAgentsRetiredLocally?: boolean;
+    retiredAgentIds?: readonly string[];
     setupChallengeExpiresAt?: string;
     approvalRequired: boolean;
+    approvalUrl?: string;
 }): ConnectOutcome;
 /**
  * The failure record for the `--json` contract.
@@ -868,6 +1105,19 @@ interface ConnectErrorDetails {
      */
     installedClients?: readonly string[];
     suggestedRuntime?: string;
+    /**
+     * #2551: the agents a bare-pair setup would displace, when the refusal is
+     * `wiring_collision`. Carried structurally for the same reason as
+     * `allowedRuntimes`: a `--json` caller discards prose, and the ids are what
+     * the human it relays to needs in order to decide.
+     */
+    supersededAgentIds?: readonly string[];
+    /**
+     * #2551: a valid, collision-checked `--name` the run could be re-issued
+     * with to install alongside. A proposal the human may take, never a
+     * selection the connector acts on.
+     */
+    suggestedServerName?: string;
 }
 declare class ConnectError extends Error {
     readonly code: string;
@@ -879,11 +1129,11 @@ declare function isConnectError(err: unknown): err is ConnectError;
 
 declare const MCP_RUNTIME_MANIFEST: {
     readonly mcpPackage: "@haven_ai/mcp";
-    readonly mcpVersion: "0.1.34-alpha.0";
+    readonly mcpVersion: "0.1.35-alpha.0";
     readonly sdkPackage: "@haven_ai/sdk";
-    readonly sdkVersion: "0.1.34-alpha.0";
+    readonly sdkVersion: "0.1.35-alpha.0";
     readonly signerPackage: "@haven_ai/signer";
-    readonly signerVersion: "0.1.34-alpha.0";
+    readonly signerVersion: "0.1.35-alpha.0";
     readonly minimumNodeVersion: "22.0.0";
     readonly supportedClients: readonly ["codex-cli", "codex-desktop", "claude-code"];
     readonly requiredTools: readonly string[];