@haven_ai/connect 0.1.6-alpha → 0.1.11-alpha.0

package/README.md

@@ -8,7 +8,7 @@ public signing address, proof signature, and API-key hash. Haven never receives
 the private key or plaintext API key.
 
 ```sh
-npx -y @haven_ai/connect@0.1.3-alpha --setup hv_setup_... --api https://api.haven.example --ack-local-tools --runtime claude-code
+npx -y @haven_ai/connect@alpha --setup hv_setup_... --api https://api.haven.example --ack-local-tools --runtime claude-code
 ```
 
 The connector writes owner-only credential files outside the project by default:

package/dist/cli.cjs

@@ -60,6 +60,7 @@ function createConnectApiClient(baseUrl, fetchImpl = fetch) {
           signer_acknowledged: input.signerAcknowledged,
           local_mcp_acknowledged: input.localMcpAcknowledged,
           activation_command_available: input.activationCommandAvailable,
+          skill_installed: input.skillInstalled,
           probe_result: input.probeResult,
           restart_required: input.restartRequired,
           next_user_action: input.nextUserAction,
@@ -212,9 +213,9 @@ var MCP_RUNTIME_MANIFEST = {
   mcpPackage: "@haven_ai/mcp",
   mcpVersion: mcp.MCP_VERSION,
   sdkPackage: "@haven_ai/sdk",
-  sdkVersion: "0.1.9",
+  sdkVersion: "0.1.11-alpha.0",
   signerPackage: "@haven_ai/signer",
-  signerVersion: "0.1.3-alpha",
+  signerVersion: "0.1.11-alpha.0",
   minimumNodeVersion: "20.0.0",
   supportedClients: ["codex-cli", "codex-desktop", "claude-code"],
   requiredTools: mcp.registeredToolNames()
@@ -419,6 +420,26 @@ function mergeCodexToml(existingToml, localMcpCommand) {
   validateCodexToml(block, "Generated Codex Haven config");
   const merged = `${next ? `${next}
 
+` : ""}${block}
+`;
+  return merged;
+}
+function mergeCodexTomlHosted(existingToml, hostedMcpUrl, apiKey, signerPath) {
+  let next = removeTomlTableTree(removeTomlTableTree(existingToml, "mcp_servers.haven"), "mcp_servers.haven_signer");
+  next = next.trimEnd();
+  const block = [
+    "[mcp_servers.haven]",
+    `url = ${tomlString(hostedMcpUrl)}`,
+    `http_headers = { "Authorization" = ${tomlString(`Bearer ${apiKey}`)} }`,
+    "",
+    "[mcp_servers.haven_signer]",
+    'command = "npx"',
+    `args = ["-y", ${tomlString(signerPackageSpec())}, "--credentials", ${tomlString(signerPath)}]`,
+    "startup_timeout_sec = 120"
+  ].join("\n");
+  validateCodexToml(block, "Generated Codex Haven config");
+  const merged = `${next ? `${next}
+
 ` : ""}${block}
 `;
   return merged;
@@ -459,27 +480,46 @@ async function writeJsonRuntimeConfig(input, target, serverRoot) {
 }
 async function writeCodexConfig(input) {
   const target = codexConfigPath(input.homeDir);
+  const local = input.mode === "local";
+  const restartMessage = runtimeRequiresHardRestart(input.runtime) ? "After Haven approval, restart Codex Desktop so it can load Haven tools." : "After Haven approval, Haven tools should appear in your next Codex message. If they don't, restart Codex to load them.";
   try {
     const existing = await readOptional(target);
-    if (!input.localMcpCommand) {
-      throw new Error("local MCP wrapper command is required");
+    if (local) {
+      if (!input.localMcpCommand) {
+        throw new Error("local MCP wrapper command is required");
+      }
+      const merged2 = mergeCodexToml(existing ?? "", input.localMcpCommand);
+      await writeOwnerOnlyText(target, merged2);
+      return {
+        hostedConfigured: false,
+        signerConfigured: true,
+        localMcpConfigured: true,
+        runtimeMcpMode: "local_stdio",
+        target: configTargetLabel(input.runtime),
+        changed: existing !== merged2,
+        restartRequired: true,
+        messages: [
+          `Updated local Haven MCP entry in ${configTargetLabel(input.runtime)}.`,
+          // Codex Desktop loads MCP servers at app launch; Codex CLI typically
+          // picks them up in the next session. Branch the copy so desktop users
+          // get the unambiguous instruction.
+          restartMessage
+        ]
+      };
     }
-    const merged = mergeCodexToml(existing ?? "", input.localMcpCommand);
+    const merged = mergeCodexTomlHosted(existing ?? "", input.hostedMcpUrl, input.apiKey, input.signerPath);
     await writeOwnerOnlyText(target, merged);
     return {
-      hostedConfigured: false,
+      hostedConfigured: true,
       signerConfigured: true,
-      localMcpConfigured: true,
-      runtimeMcpMode: "local_stdio",
+      localMcpConfigured: false,
+      runtimeMcpMode: "hosted_plus_signer",
       target: configTargetLabel(input.runtime),
       changed: existing !== merged,
       restartRequired: true,
       messages: [
-        `Updated local Haven MCP entry in ${configTargetLabel(input.runtime)}.`,
-        // Codex Desktop loads MCP servers at app launch; Codex CLI typically
-        // picks them up in the next session. Branch the copy so desktop users
-        // get the unambiguous instruction.
-        runtimeRequiresHardRestart(input.runtime) ? "After Haven approval, restart Codex Desktop so it can load Haven tools." : "After Haven approval, Haven tools should appear in your next Codex message. If they don't, restart Codex to load them."
+        `Updated Haven MCP entries in ${configTargetLabel(input.runtime)}.`,
+        restartMessage
       ]
     };
   } catch (err) {
@@ -488,7 +528,7 @@ async function writeCodexConfig(input) {
       hostedConfigured: false,
       signerConfigured: false,
       localMcpConfigured: false,
-      runtimeMcpMode: "local_stdio",
+      runtimeMcpMode: local ? "local_stdio" : "hosted_plus_signer",
       target: configTargetLabel(input.runtime),
       changed: false,
       restartRequired: true,
@@ -868,7 +908,7 @@ async function probeLocalSignerCredential(signerPath) {
   }
 }
 async function probeLocalMcpTools(command, args, requiredTools, timeoutMs = 1e4) {
-  return new Promise((resolve6) => {
+  return new Promise((resolve7) => {
     const child = child_process.spawn(command, args, { stdio: ["pipe", "pipe", "ignore"] });
     let stdout = "";
     let settled = false;
@@ -878,7 +918,7 @@ async function probeLocalMcpTools(command, args, requiredTools, timeoutMs = 1e4)
       settled = true;
       clearTimeout(timeout);
       child.kill();
-      resolve6(result);
+      resolve7(result);
     };
     const timeout = setTimeout(() => finish({ status: "timeout" }), timeoutMs);
     child.on("error", () => finish({ status: "process_error" }));
@@ -1116,6 +1156,75 @@ async function assertFileExists(path, label) {
     throw new Error(`Missing ${label}: ${path}`);
   }
 }
+
+// src/skill-content.ts
+var HAVEN_SKILL_MD = `---
+name: haven-pay
+description: Pay for things from the user's Haven wallet within their agent rules. Use when the user asks to send, pay, tip, or transfer crypto \u2014 or when a request hits an HTTP 402 (x402) paywall.
+---
+
+# Haven: pay from a Haven wallet
+
+This skill lets the agent make payments from the user's Haven wallet through
+the Haven MCP tools. Every payment is checked against the agent's on-chain
+budget before money moves; payments above the remaining budget wait for the
+user's approval in Haven.
+
+## When to use this skill
+
+- The user asks to send money, pay someone, tip, donate, or transfer tokens.
+- A request returns HTTP 402 (x402): use the Haven pay tools to settle it,
+  then retry the original request.
+
+## Identity and budget come from the tools \u2014 never assume them
+
+Do not guess the wallet address, network, or budget. Read them live:
+
+- \`haven_get_agent\` \u2014 agent identity, Haven wallet address, network.
+- \`haven_get_allowances\` \u2014 current per-token budgets and what remains.
+
+Budgets reset on a period the user chose. If a payment exceeds the remaining
+budget it is queued for the user to approve in the Haven dashboard \u2014 this is
+normal, not an error.
+
+## Paying
+
+- **Direct transfer:** \`haven_pay\` with recipient, amount, and token.
+- **x402 paywall:** \`haven_quote_x402\` to get a quote, then
+  \`haven_pay_x402_quote\`. In the hosted setup the signing step happens in
+  the local Haven signer; follow the tool results \u2014 they tell you the next
+  action at every step. Retry the original request only when the result says
+  \`retry_original_x402_request\`.
+- **Status:** \`haven_get_payment_status\` with a \`payment_id\` to check on
+  queued or in-flight payments. Do not poll in a tight loop.
+
+## Approval semantics
+
+- A result with \`pending_approval\` means the payment exceeded the remaining
+  budget and is waiting for the user in Haven. Tell the user, then check
+  status later.
+- Never ask the user for private keys and never try to sign anything
+  yourself \u2014 Haven signs. If a tool reports a missing or invalid credential,
+  tell the user to re-run the Haven setup command.
+
+## Failure handling
+
+Haven errors are shaped \`{ error, status, details? }\` and written for
+humans \u2014 surface the message verbatim. Common cases:
+
+- \`pending_approval\`: queued for the user's approval (see above).
+- \`insufficient_funds\`: the Haven wallet doesn't hold enough of that token.
+  Suggest the user add funds in the Haven dashboard.
+- Budget exceeded: tell the user how much remains (from
+  \`haven_get_allowances\`) and that they can raise the budget in Haven.
+
+## Revoke
+
+If this agent's credential may have leaked, tell the user to pause or revoke
+the agent in the Haven dashboard under Agents. New requests stop immediately
+for that credential.
+`;
+var SKILL_FOLDER_NAME = "haven-pay";
 async function acknowledgeLocalSignerConsent(signerPath, log) {
   try {
     const input = await buildSignerConsentInput(signerPath);
@@ -1191,7 +1300,7 @@ var execFileAsync2 = util.promisify(child_process.execFile);
 async function installRuntime(input, deps = {}) {
   const runtime = normalizeRuntime(input.runtime, deps.env);
   const profile = runtimeProfile(runtime, deps.env);
-  const localRuntime = usesLocalMcp(runtime);
+  const localRuntime = input.localMcp === true && supportsLocalMcp(runtime);
   const consentMessages = [];
   const localMcpConsent = localRuntime ? await resolveLocalMcpConsent(input, consentMessages) : void 0;
   const signerConsent = localRuntime ? void 0 : await resolveSignerConsent(input, consentMessages);
@@ -1248,7 +1357,7 @@ async function installRuntime(input, deps = {}) {
       ]
     };
   }
-  const configResult = runtime === "claude-code" ? await configureClaudeCode(deps, localRuntimeInstall?.command ?? "") : await writeRuntimeConfig({
+  const configResult = runtime === "claude-code" ? localRuntime ? await configureClaudeCode(deps, localRuntimeInstall?.command ?? "") : await configureClaudeCodeHosted(deps, input) : await writeRuntimeConfig({
     runtime,
     hostedMcpUrl: input.hostedMcpUrl,
     apiKey: input.apiKey,
@@ -1256,7 +1365,8 @@ async function installRuntime(input, deps = {}) {
     signerPath: input.signerPath,
     credentialDirectory: input.credentialDirectory,
     localMcpCommand: localRuntimeInstall?.command,
-    homeDir: deps.homeDir
+    homeDir: deps.homeDir,
+    mode: localRuntime ? "local" : "hosted"
   });
   const localProbePromise = configResult.runtimeMcpMode === "local_stdio" && localRuntimeInstall ? runLocalMcpProbe(localRuntimeInstall, deps) : Promise.resolve(void 0);
   const [hostedProbe, signerCredentialReady, localMcpProbe] = await Promise.all([
@@ -1270,6 +1380,7 @@ async function installRuntime(input, deps = {}) {
   const restartRequired = configResult.restartRequired || restartRequiredForRuntime(runtime, deps.env);
   const errorCode = configResult.errorCode ?? (configResult.runtimeMcpMode === "local_stdio" ? localMcpErrorCode(signerCredentialReady, localMcpConsent, localMcpProbe?.status) : signerConsentErrorCode(signerCredentialReady, signerConsent));
   const localProbeMessages = localMcpProbe && localMcpProbe.status !== "ok" ? [`Local Haven MCP handshake failed: ${localMcpProbe.status}.`] : localMcpProbe?.status === "ok" ? ["Verified local Haven MCP tools with a stdio handshake."] : [];
+  const skillInstall = runtime === "claude-code" && !configResult.errorCode ? await installClaudeSkill(deps.homeDir) : void 0;
   return {
     runtime,
     runtimeMcpMode: configResult.runtimeMcpMode,
@@ -1284,7 +1395,8 @@ async function installRuntime(input, deps = {}) {
     signerAcknowledged: signerConsent?.acknowledged,
     localMcpAcknowledged: localMcpConsent?.acknowledged,
     activationCommand: configResult.activationCommand,
-    messages: [...consentMessages, ...localRuntimeInstall?.messages ?? [], ...configResult.messages, ...localProbeMessages]
+    skillInstalled: skillInstall?.installed,
+    messages: [...consentMessages, ...localRuntimeInstall?.messages ?? [], ...configResult.messages, ...localProbeMessages, ...skillInstall?.messages ?? []]
   };
 }
 function runtimeInstallCapabilities(runtime, env = process.env) {
@@ -1340,9 +1452,75 @@ async function configureClaudeCode(deps, localMcpCommand) {
     };
   }
 }
+async function configureClaudeCodeHosted(deps, input) {
+  const runCommand = deps.runCommand ?? defaultRunCommand;
+  const hostedJson = JSON.stringify({
+    type: "http",
+    url: input.hostedMcpUrl,
+    headers: { Authorization: `Bearer ${input.apiKey}` }
+  });
+  const signerJson = JSON.stringify({
+    type: "stdio",
+    command: "npx",
+    args: ["-y", signerPackageSpec(), "--credentials", input.signerPath],
+    env: {}
+  });
+  try {
+    await runCommand("claude", ["mcp", "remove", "haven"]).catch(() => void 0);
+    await runCommand("claude", ["mcp", "remove", "haven-signer"]).catch(() => void 0);
+    await runCommand("claude", ["mcp", "add-json", "haven", hostedJson, "--scope", "user"]);
+    await runCommand("claude", ["mcp", "add-json", "haven-signer", signerJson, "--scope", "user"]);
+    const verified = await runCommand("claude", ["mcp", "get", "haven"]).then(() => true).catch(() => false);
+    return {
+      hostedConfigured: true,
+      signerConfigured: true,
+      localMcpConfigured: false,
+      runtimeMcpMode: "hosted_plus_signer",
+      target: "Claude Code MCP config",
+      changed: true,
+      restartRequired: true,
+      messages: [
+        "Updated hosted Haven MCP and local signer entries with Claude Code.",
+        ...verified ? ["Verified Claude Code MCP entry."] : [],
+        "After Haven approval, Haven tools should appear in your next Claude Code message. If they don't, restart the session to load them."
+      ]
+    };
+  } catch (err) {
+    return {
+      hostedConfigured: false,
+      signerConfigured: false,
+      localMcpConfigured: false,
+      runtimeMcpMode: "hosted_plus_signer",
+      target: "Claude Code MCP config",
+      changed: false,
+      restartRequired: true,
+      messages: [
+        `Could not update Claude Code MCP config: ${err instanceof Error ? err.message : String(err)}`,
+        "Install Claude Code or rerun the Haven setup command inside a Claude Code terminal."
+      ],
+      errorCode: "claude_code_config_failed"
+    };
+  }
+}
 async function defaultRunCommand(command, args) {
   await execFileAsync2(command, args, { timeout: 1e4 });
 }
+async function installClaudeSkill(homeDir) {
+  try {
+    const skillDir = path.resolve(homeDir ?? os.homedir(), ".claude", "skills", SKILL_FOLDER_NAME);
+    await promises.mkdir(skillDir, { recursive: true });
+    await promises.writeFile(path.join(skillDir, "SKILL.md"), HAVEN_SKILL_MD, "utf8");
+    return {
+      installed: true,
+      messages: ["Installed the generic Haven payment skill (~/.claude/skills/haven-pay). It contains no secrets."]
+    };
+  } catch (err) {
+    return {
+      installed: false,
+      messages: [`Could not install the Haven payment skill: ${err instanceof Error ? err.message : String(err)}. Download it from the Haven dashboard instead.`]
+    };
+  }
+}
 function buildProbeResult(mode, hostedConfigured, hostedStatus, signerReady, localMcpReady, localMcpProbeStatus) {
   if (mode === "local_stdio") {
     if (localMcpReady) return "local_stdio_mcp_ready";
@@ -1396,7 +1574,7 @@ function nextAction(runtime, restartMode, errorCode) {
   if (restartMode === "restart-session") return "return_to_haven_for_wallet_approval_then_restart_agent_session";
   return "return_to_haven_for_wallet_approval_then_configure_runtime";
 }
-function usesLocalMcp(runtime) {
+function supportsLocalMcp(runtime) {
   return runtime === "codex-cli" || runtime === "codex-desktop" || runtime === "claude-code";
 }
 async function prepareRuntimeForLocalMcp(input, deps) {
@@ -1424,7 +1602,7 @@ function localRuntimePrepareErrorCode(err) {
 }
 
 // src/runtime.ts
-var CONNECTOR_VERSION = "0.1.2";
+var CONNECTOR_VERSION = "0.1.11-alpha.0";
 async function runConnect(options, deps = {}) {
   const connectorVersion = options.connectorVersion ?? CONNECTOR_VERSION;
   const api = deps.api ?? createConnectApiClient(options.apiBaseUrl);
@@ -1436,6 +1614,14 @@ async function runConnect(options, deps = {}) {
   const generateKey = deps.generateKey ?? generateDelegateKey;
   const generateLocalApiKey = deps.generateApiKey ?? generateAgentApiKey;
   const installCapabilities = runtimeInstallCapabilities(options.runtime);
+  if (options.localMcp) {
+    const resolvedRuntime = normalizeRuntime(options.runtime);
+    if (!supportsLocalMcp(resolvedRuntime)) {
+      throw new Error(
+        `--local (fully-local Haven MCP) is only available for Claude Code and Codex. The detected runtime is ${runtimeProfile(resolvedRuntime).label}. Re-run without --local to use the default hosted MCP + local signer setup.`
+      );
+    }
+  }
   const setup = await api.resolveSetup({
     setupToken: options.setupToken,
     connectorVersion,
@@ -1494,7 +1680,8 @@ async function runConnect(options, deps = {}) {
     credentialDirectory: credentialPaths.directory,
     environmentLabel: options.environmentLabel ?? "Local workspace",
     ackSigner: options.ackSigner,
-    ackLocalTools: options.ackLocalTools
+    ackLocalTools: options.ackLocalTools,
+    localMcp: options.localMcp
   });
   printRuntimeInstall(runtimeInstall, log);
   try {
@@ -1509,6 +1696,7 @@ async function runConnect(options, deps = {}) {
       signerAcknowledged: runtimeInstall.signerAcknowledged,
       localMcpAcknowledged: runtimeInstall.localMcpAcknowledged,
       activationCommandAvailable: Boolean(runtimeInstall.activationCommand),
+      skillInstalled: runtimeInstall.skillInstalled,
       probeResult: runtimeInstall.probeResult,
       restartRequired: runtimeInstall.restartRequired,
       nextUserAction: runtimeInstall.nextUserAction,
@@ -1590,6 +1778,8 @@ function parseArgs(argv, env = process.env) {
     } else if (arg === "--ack-signer") {
       options.ackSigner = true;
       options.ackLocalTools = true;
+    } else if (arg === "--local" || arg === "--local-mcp") {
+      options.localMcp = true;
     } else if (arg === "--version") {
       process.stdout.write(`${CONNECTOR_VERSION}
 `);
@@ -1628,6 +1818,8 @@ function helpText() {
     "  --environment-label <text> Non-sensitive label shown in Haven setup review.",
     "  --ack-local-tools          Write the one-time local Haven tools acknowledgement during setup.",
     "  --ack-signer               Backward-compatible alias for --ack-local-tools.",
+    "  --local                    Advanced: install the fully-local Haven MCP (no hosted dependency).",
+    "                             Only available for Claude Code and Codex. Default is hosted MCP + local signer.",
     "  --help                     Show this help.",
     "",
     "The connector never prints the private key and never sends it to Haven."