kojee-mcp 0.7.5-staging.2 → 0.7.5-staging.3

package/README.md

@@ -11,7 +11,7 @@ There are three ways to connect Kojee to an MCP-capable agent:
 
 1. **Mobile, web & desktop (recommended for chat clients)** — paste the Kojee MCP URL into the app's "Add custom connector" dialog. The app handles OAuth login and consent. No local install. Works on Claude (web/desktop/iOS/Android) and ChatGPT (web/desktop/iOS/Android with Developer Mode enabled).
 2. **Claude Code / Codex / Cursor — the local stdio proxy.** Run `kojee-mcp` locally; it holds a `gw_` gateway token + ES256 keypair and signs every request with DPoP (RFC 9449). The runtime-aware [`init` wizard](#quick-start-claude-code--tandem) wires it into your harness and sets up the wake path so an idle agent is woken by Tandem messages between turns. **This is the recommended path for agentic runtimes** and the focus of this README.
-3. **OpenClaw / Hermes — native Tandem channel plugins.** On those runtimes Tandem is a first-class channel (peer to Telegram/Discord), wired through a plugin that wraps the same gateway client — **not** MCP. See [Native gateway runtimes](#native-gateway-runtimes-openclaw--hermes).
+3. **OpenClaw / Hermes — native gateway runtimes.** On those runtimes kojee is registered as the agent's MCP server (so the agent can explore + call kojee tools), and Tandem is a first-class channel wired through the gateway (an in-gateway MCP wake injector on OpenClaw; a sidecar daemon + channel plugin on Hermes). See [Native gateway runtimes](#native-gateway-runtimes-openclaw--hermes).
 
 ## Mobile, Web & Desktop (Recommended)
 

package/dist/{chunk-XPIW4N55.js → chunk-QNGMMBOD.js}

@@ -135,8 +135,8 @@ function pairSlotFor(runtime, code) {
 
 // src/wizard/wizard.ts
 import crypto3 from "crypto";
-import fs6 from "fs";
-import path7 from "path";
+import fs7 from "fs";
+import path8 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/wizard/skill-install.ts
@@ -350,7 +350,8 @@ function writeWebhookSecretBothSides(opts) {
     ["KOJEE_RUNTIME", opts.runtime],
     ["KOJEE_WEBHOOK_URL", opts.webhookUrl],
     ["KOJEE_WEBHOOK_SECRET", secret],
-    ...opts.signatureEnv ?? []
+    ...opts.signatureEnv ?? [],
+    ...opts.daemonExtraEnv ?? []
   ];
   upsertEnvFile(opts.daemonEnvPath, daemonVars, {
     exportPrefix: true,
@@ -368,7 +369,7 @@ function writeWebhookSecretBothSides(opts) {
 }
 
 // src/wizard/installers/hermes.ts
-import path6 from "path";
+import path7 from "path";
 
 // src/wizard/plugin-payload.ts
 import fs4 from "fs";
@@ -507,17 +508,100 @@ function writeService(platform, spec) {
   return plan;
 }
 
+// src/wizard/capabilities/hermes-mcp-config.ts
+import fs6 from "fs";
+import path6 from "path";
+import { parseDocument, isMap } from "yaml";
+var HERMES_MCP_SERVER_NAME = "kojee";
+var HERMES_INSTANCE_KEY = "hermes-gateway";
+var HERMES_MCP_CONNECT_TIMEOUT_S = 120;
+function defaultHermesConfigPath(homeDir) {
+  return path6.join(homeDir, ".hermes", "config.yaml");
+}
+function buildKojeeEntry(binPath) {
+  return {
+    command: binPath,
+    args: [],
+    env: {
+      KOJEE_RUNTIME: "hermes",
+      KOJEE_INSTANCE: HERMES_INSTANCE_KEY,
+      // Vanilla tools-only proxy: NEVER a second webhook delivery (see header).
+      KOJEE_WEBHOOK_URL: ""
+    },
+    connect_timeout: HERMES_MCP_CONNECT_TIMEOUT_S
+  };
+}
+function resolveMode(filePath) {
+  try {
+    return fs6.statSync(filePath).mode & 511;
+  } catch {
+    return 384;
+  }
+}
+function atomicWrite(filePath, content, mode) {
+  fs6.mkdirSync(path6.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+  fs6.writeFileSync(tmp, content, { mode });
+  fs6.renameSync(tmp, filePath);
+}
+function backupSuffix(now) {
+  return (now ? now() : /* @__PURE__ */ new Date()).toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+}
+function writeHermesMcpConfig(configPath, opts) {
+  let raw = null;
+  try {
+    raw = fs6.readFileSync(configPath, "utf8");
+  } catch {
+    raw = null;
+  }
+  let backedUp;
+  let doc = parseDocument("");
+  if (raw !== null && raw.trim() !== "") {
+    const parsed = parseDocument(raw);
+    if (parsed.errors.length > 0) {
+      backedUp = `${configPath}.corrupt-${backupSuffix(opts.now)}`;
+      fs6.copyFileSync(configPath, backedUp);
+    } else {
+      doc = parsed;
+    }
+  }
+  if (doc.hasIn(["mcp_servers"]) && !isMap(doc.getIn(["mcp_servers"], true))) {
+    doc.deleteIn(["mcp_servers"]);
+  }
+  doc.setIn(["mcp_servers", HERMES_MCP_SERVER_NAME], buildKojeeEntry(opts.binPath));
+  atomicWrite(configPath, String(doc), resolveMode(configPath));
+  return { configPath, ...backedUp ? { backedUp } : {} };
+}
+function removeHermesMcpServer(configPath) {
+  let raw;
+  try {
+    raw = fs6.readFileSync(configPath, "utf8");
+  } catch {
+    return false;
+  }
+  const doc = parseDocument(raw);
+  if (doc.errors.length > 0) return false;
+  if (!doc.hasIn(["mcp_servers", HERMES_MCP_SERVER_NAME])) return false;
+  doc.deleteIn(["mcp_servers", HERMES_MCP_SERVER_NAME]);
+  const servers = doc.getIn(["mcp_servers"], true);
+  if (isMap(servers) && servers.items.length === 0) {
+    doc.deleteIn(["mcp_servers"]);
+  }
+  atomicWrite(configPath, String(doc), resolveMode(configPath));
+  return true;
+}
+
 // src/wizard/installers/hermes.ts
 function installHermes(inp) {
-  const daemonEnv = path6.join(inp.homeDir, ".kojee", "hermes.env");
-  const adapterEnv = path6.join(inp.homeDir, ".hermes", ".env");
-  const pluginDir = path6.join(inp.homeDir, ".hermes", "plugins", "kojee-tandem");
+  const daemonEnv = path7.join(inp.homeDir, ".kojee", "hermes.env");
+  const adapterEnv = path7.join(inp.homeDir, ".hermes", ".env");
+  const pluginDir = path7.join(inp.homeDir, ".hermes", "plugins", "kojee-tandem");
   if (!inp.skipPayload) {
     const missing = missingPayloadFiles("hermes", inp.payloadBaseDir, HERMES_PAYLOAD_FILES);
     if (missing.length > 0) {
       return {
         runtime: "hermes",
-        output: `hermes install ERROR: the bundled plugin payload is incomplete \u2014 missing ${missing.join(", ")} under ${path6.join(inp.payloadBaseDir, "plugins", "hermes")}. No changes were written. Run \`npm run build\` to stage dist/plugins/hermes, then retry.`,
+        output: `hermes install ERROR: the bundled plugin payload is incomplete \u2014 missing ${missing.join(", ")} under ${path7.join(inp.payloadBaseDir, "plugins", "hermes")}. No changes were written. Run \`npm run build\` to stage dist/plugins/hermes, then retry.`,
         exitCode: 2,
         secret: "",
         secretReused: false
@@ -529,11 +613,14 @@ function installHermes(inp) {
     adapterEnvPath: adapterEnv,
     webhookUrl: inp.webhookUrl,
     runtime: "hermes",
+    daemonExtraEnv: [["KOJEE_INSTANCE", HERMES_INSTANCE_KEY]],
     ...inp.mcpDir ? { mcpDir: inp.mcpDir } : {},
     ...inp.allowAllUsers ? { allowAllUsers: true } : {},
     ...inp.signatureEnv && inp.signatureEnv.length > 0 ? { signatureEnv: inp.signatureEnv } : {},
     ...inp.webhookSecret ? { existingSecret: inp.webhookSecret } : {}
   });
+  const hermesConfig = defaultHermesConfigPath(inp.homeDir);
+  const mcp = writeHermesMcpConfig(hermesConfig, { binPath: inp.binPath });
   const staged = inp.skipPayload ? [] : installBundledPayload({
     runtime: "hermes",
     baseDir: inp.payloadBaseDir,
@@ -552,6 +639,8 @@ function installHermes(inp) {
     `  secret:      ${sec.reused ? "reused existing" : "generated"} (matched on daemon + adapter env)`,
     `  daemon env:  ${daemonEnv}`,
     `  adapter env: ${adapterEnv}`,
+    `  mcp config:  ${hermesConfig} (mcp_servers.kojee \u2014 agent explores kojee via mcp_kojee_*)`,
+    ...mcp.backedUp ? [`  NOTE: prior ${hermesConfig} was unparseable; backed up to ${mcp.backedUp} before writing.`] : [],
     inp.skipPayload ? `  plugin:      SKIPPED \u2014 no bundled payload (run \`npm run build\` to stage dist/plugins/hermes)` : `  plugin:      ${pluginDir} (${staged.length} files)`,
     svc.supported ? `  service:     ${svc.unitPath}` : `  service:     manual \u2014 ${svc.note ?? "unsupported platform"}`,
     // NB: the "Receiver contract" section is intentionally NOT printed here.
@@ -561,9 +650,13 @@ function installHermes(inp) {
     "",
     "Next:",
     `  - start the daemon service:  ${svc.activateCmd}`,
-    "  - reload the Hermes gateway to load the plugin:  systemctl --user restart hermes-gateway (or: hermes gateway restart)",
-    "  - join a tandem once:  tandem_join <tandem_id>",
-    "  - verify:  kojee-mcp doctor"
+    "  - reload the Hermes gateway to load the channel plugin AND the kojee MCP server:",
+    "      systemctl --user restart hermes-gateway   (or: hermes gateway restart, or /reload-mcp)",
+    "  - verify the MCP registered:  hermes mcp test kojee   (tools appear to the agent as mcp_kojee_*)",
+    "  - the agent can now join from its own tools:  mcp_kojee_tandem_join <tandem_id>",
+    "  - verify the daemon/channel:  kojee-mcp doctor",
+    "  - if tools don't register: ensure Hermes was installed with the MCP extra",
+    '      (cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]") and re-check connect_timeout.'
   ];
   return {
     runtime: "hermes",
@@ -937,7 +1030,7 @@ function buildDaemonEnvBlock(runtime, wh, envFile) {
   return lines;
 }
 function distDir() {
-  return path7.dirname(fileURLToPath2(import.meta.url));
+  return path8.dirname(fileURLToPath2(import.meta.url));
 }
 function resolveBinPath() {
   const entry = process.argv[1];
@@ -955,7 +1048,10 @@ function configureHermes(opts) {
   opts = effectiveOpts;
   const lines = [];
   lines.push(`Configured runtime: ${runtime}`);
-  lines.push("Wake mode: webhook sink (daemon-consumed). NO MCP-config file, NO hooks written.");
+  lines.push(
+    "Wake mode: webhook sink (daemon-consumed). ALSO registers kojee as the Hermes agent's",
+    "MCP server (mcp_servers.kojee) so the agent can explore kojee tools. NO hooks written."
+  );
   lines.push("");
   if (!suppliedUrl) {
     lines.push(
@@ -998,7 +1094,7 @@ function configureHermes(opts) {
       return { runtime, output: lines.join("\n"), exitCode: install.exitCode };
     }
     recordRuntime(runtime);
-    const envFile = path7.join(home, ".kojee", "hermes.env");
+    const envFile = path8.join(home, ".kojee", "hermes.env");
     lines.push(...buildDaemonEnvBlock(runtime, wh, envFile));
     lines.push("");
     lines.push(install.output);
@@ -1020,7 +1116,7 @@ function configureHermes(opts) {
   return { runtime, output: lines.join("\n"), exitCode: 0 };
 }
 function openclawConfigPath(opts) {
-  return opts.openclawConfigPath ?? path7.join(kojeeHomeDir(), ".openclaw", "openclaw.json");
+  return opts.openclawConfigPath ?? path8.join(kojeeHomeDir(), ".openclaw", "openclaw.json");
 }
 function configureOpenclaw(opts) {
   const runtime = "openclaw";
@@ -1062,11 +1158,15 @@ async function runWizardUninstall(runtime, opts) {
     const un = uninstallOpenclaw({ openclawConfigPath: openclawConfigPath(opts) });
     lines.push(un.output);
   } else {
-    lines.push("  (hermes writes no MCP-config or hooks \u2014 nothing to tear down.");
-    lines.push("   Stop the daemon and unset KOJEE_WEBHOOK_URL/SECRET to disable the sink.)");
-    const envPath = path7.join(kojeeHomeDir(), ".kojee", `${effective}.env`);
+    const hermesConfig = defaultHermesConfigPath(kojeeHomeDir());
+    const removedMcp = removeHermesMcpServer(hermesConfig);
+    lines.push(
+      removedMcp ? `  removed mcp_servers.kojee from ${hermesConfig} (operator config preserved)` : `  no mcp_servers.kojee in ${hermesConfig} \u2014 nothing to remove`
+    );
+    lines.push("  (stop the daemon service + reload the gateway to disable the webhook wake path.)");
+    const envPath = path8.join(kojeeHomeDir(), ".kojee", `${effective}.env`);
     try {
-      fs6.unlinkSync(envPath);
+      fs7.unlinkSync(envPath);
       lines.push(`  removed ${envPath}`);
     } catch {
     }
@@ -1109,7 +1209,11 @@ registerBuiltinInstaller(
     "webhook",
     "webhook-secret-both-sides",
     "plugin-payload-copy",
-    "service-install"
+    "service-install",
+    // kojee registered as the Hermes agent's MCP server (mcp_servers.kojee in
+    // ~/.hermes/config.yaml) so the agent can EXPLORE + call kojee tools —
+    // additive to the channel plugin, does not change the webhook wake path.
+    "mcp-config-write"
   ],
   (o) => configureHermes(o)
 );

package/dist/cli.js

@@ -48,7 +48,7 @@ program.command("pair <code>").description("Pair this machine against Kojee usin
 program.command("connect <code>").description(
   "Connect this runtime to Kojee with a per-agent pair code from the dashboard (claude-code | codex | openclaw | hermes). claude-code/codex/openclaw write a per-runtime paired slot (~/.kojee/agents/<runtime>/config.json) and point the runtime launcher at it via --paired-config; hermes writes the global ~/.kojee/config.json (its daemon + `kojee-mcp send` read that). Idempotent."
 ).requiredOption("--runtime <id>", "Target runtime: claude-code | codex | openclaw | hermes").option("--url <url>", "Broker base URL (default: the canonical staging broker)").action(async (code, opts) => {
-  const { runConnect } = await import("./connect-handler-NZINEMG3.js");
+  const { runConnect } = await import("./connect-handler-D3VQMUIS.js");
   const result = await runConnect({
     code,
     runtime: opts.runtime,
@@ -143,7 +143,7 @@ function addInstallOptions(cmd, runtimeHelp) {
 function makeInstallAction(verb) {
   return async (opts) => {
     const interactive = process.stdin.isTTY === true && opts.runtime === void 0;
-    const { runSetup, resolvePairCode } = await import("./setup-handler-44ASXYMS.js");
+    const { runSetup, resolvePairCode } = await import("./setup-handler-5Q47JYPQ.js");
     const pairCode = resolvePairCode(opts);
     const result = await runSetup({
       verb,

package/dist/{connect-handler-NZINEMG3.js → connect-handler-D3VQMUIS.js}

@@ -2,7 +2,7 @@ import {
   DEFAULT_BROKER_URL,
   reconcileConnectPairSlot,
   runWizard
-} from "./chunk-XPIW4N55.js";
+} from "./chunk-QNGMMBOD.js";
 import "./chunk-6XWTUDWW.js";
 import "./chunk-E6WMFMM2.js";
 import "./chunk-77HWBSRH.js";

package/dist/{setup-handler-44ASXYMS.js → setup-handler-5Q47JYPQ.js}

@@ -3,7 +3,7 @@ import {
   pairSlotFor,
   reconcileConnectPairSlot,
   runWizard
-} from "./chunk-XPIW4N55.js";
+} from "./chunk-QNGMMBOD.js";
 import "./chunk-6XWTUDWW.js";
 import "./chunk-E6WMFMM2.js";
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kojee-mcp",
-  "version": "0.7.5-staging.2",
+  "version": "0.7.5-staging.3",
   "type": "module",
   "main": "dist/index.js",
   "exports": {
@@ -35,6 +35,7 @@
     "ps-list": "^8.1.1",
     "ulidx": "^2.3.0",
     "undici": "^8.5.0",
+    "yaml": "^2.9.0",
     "zod": "^3.22.0"
   },
   "devDependencies": {