hermes-cursor-acp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neeraj Kumar Singh Beshane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# hermes-cursor-acp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Use your Cursor subscription models (Claude, GPT, Grok, Gemini, Composer) as the model behind [Hermes Agent](https://github.com/NousResearch/hermes-agent).
+
+Cursor doesn't expose a chat-completions API, but the Cursor CLI ships an ACP server (`agent acp`). This plugin drives it through Hermes' ACP shim. Hermes keeps its own tools, memory, and skills. Cursor only supplies the model.
+
+## How it works
+
+- Hermes tool schemas go to the model as text. The model replies with `<tool_call>` blocks, and Hermes runs those calls itself.
+- The plugin parses tool calls with its own extractor. Hermes' built-in bridge silently drops two common shapes: the flat `{"name", "arguments"}` form, and a real block that follows a mention of `<tool_call>` in prose.
+- The plugin rewrites `.cursor/cli.json` in an empty private workspace (`$HERMES_HOME/cache/cursor-acp-workspace`) every time a client starts, with a deny-all list (`Read`, `Write`, `Shell`, `WebFetch`, `Mcp`). This deny list is the security fence. Cursor's native tools run inside the CLI rather than over ACP, and without the list its Read tool can open any absolute path on disk.
+- Models can be chosen by bare name (`claude-opus-5-5`) or by full advertised id (`claude-opus-5-5[context=300k,effort=high,fast=false]`). An unknown name raises an error instead of silently using Cursor's default.
+- Responses report `usage=None`. Cursor sends no token counts, and a zero reading would stall Hermes' proactive context compression.
+
+## Install
+
+### Option 1: One-command install (recommended)
+
+```bash
+npx hermes-cursor-acp
+```
+
+This installs and enables the plugin in Hermes, verifies your Cursor CLI (`agent`) installation, and checks that your subscription models are accessible.
+
+### Option 2: Manual install
+
+```bash
+curl https://cursor.com/install -fsS | bash   # Cursor CLI
+agent login                                   # sign in with your Cursor account
+agent models                                  # confirm what your plan offers
+
+git clone git@github.com:neerazz/hermes-cursor-acp.git ~/.hermes/plugins/cursor-acp
+hermes plugins enable cursor-acp
+```
+
+## Use
+
+```bash
+hermes --provider cursor -m claude-opus-5-5
+```
+
+Or run `/model` inside Hermes and pick **Cursor Subscription (ACP)**.
+
+## Settings (env)
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `HERMES_CURSOR_ACP_COMMAND` | `agent` | Path to the Cursor CLI |
+| `HERMES_CURSOR_ACP_ARGS` | `acp` | Argv tail |
+| `HERMES_CURSOR_ACP_MODE` | `agent` | Cursor session mode. `ask` made gpt-5.6-sol refuse the bridge 2 times in 5. |
+| `HERMES_CURSOR_ACP_CWD` | `$HERMES_HOME/cache/cursor-acp-workspace` | Private workspace |
+
+## Tests
+
+```bash
+H=~/.hermes/hermes-agent
+PYTHONPATH=$H uv run --no-project --python $H/venv/bin/python --with pytest python -m pytest tests -q -o addopts=
+CURSOR_LIVE=1 ...   # adds live tests against the real CLI (needs `agent login`)
+```
+
+Live results on 2026-10-06 (Hermes v0.21.5, Cursor CLI 2026.10.01):
+
+- Hermes tool-call bridging over 6 trials per model: claude-sonnet-5-5 6/6, claude-opus-5-5 6/6, composer-2.5 6/6, grok-4.7 6/6, gpt-5.6-sol 5/6. The one gpt miss answered from context without calling the tool.
+- Fence probes sent as raw prompts, so the model was told to escape: Cursor's native Read, Grep, Shell, Write, and WebFetch were all blocked. The canary file content and a live GitHub SHA never came back.
+- End-to-end multi-step runs through `hermes chat` (read_file, then terminal) executed both tools for real with composer-2.5 and gpt-5.6-sol.
+
+## Known limits
+
+- Every turn starts a new ACP session. That adds 7–16s of latency and about 17k tokens of Cursor's harness prompt.
+- Hermes records no token or cost data for these calls, so `/usage` and `/insights` undercount.
+- When several sessions start at once, Cursor occasionally answers `set_model` with `Internal error`. The plugin retries up to 3 times.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// npx hermes-cursor-acp [install|status|uninstall]
+// Thin wrapper over the official CLIs: `hermes plugins install` and Cursor's `agent`.
+// No credentials or tokens pass through this script.
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const REPO = "https://github.com/neerazz/hermes-cursor-acp";
+const PLUGIN = "cursor-acp";
+const CURSOR_INSTALLER = "https://cursor.com/install";
+const HERMES_DOCS = "https://hermes-agent.nousresearch.com/docs";
+
+const [, , cmd = "install", ...rest] = process.argv;
+const flags = new Set(rest);
+const yes = flags.has("--yes") || flags.has("-y");
+
+function which(bin) {
+  const r = spawnSync(process.platform === "win32" ? "where" : "which", [bin], { encoding: "utf8" });
+  return r.status === 0 ? r.stdout.split(/\r?\n/)[0].trim() : null;
+}
+
+function run(bin, args, opts = {}) {
+  console.log(`$ ${bin} ${args.join(" ")}`);
+  const r = spawnSync(bin, args, { stdio: "inherit", shell: process.platform === "win32", ...opts });
+  if (r.error) throw r.error;
+  return r.status ?? 1;
+}
+
+function die(msg, code = 1) {
+  console.error(`\n✗ ${msg}`);
+  process.exit(code);
+}
+
+function requireHermes() {
+  if (!which("hermes")) {
+    die(`Hermes Agent not found on PATH. Install it first: ${HERMES_DOCS}`);
+  }
+}
+
+async function ensureCursorCli() {
+  if (which("agent")) return;
+  if (!yes) {
+    die(`Cursor CLI (agent) not found.\n  Install it with:\n    curl ${CURSOR_INSTALLER} -fsS | bash\n  or re-run with --yes to install it now.`);
+  }
+  console.log(`Installing Cursor CLI from ${CURSOR_INSTALLER}...`);
+  const code = run("bash", ["-c", `curl ${CURSOR_INSTALLER} -fsS | bash`]);
+  if (code !== 0 || !which("agent")) {
+    die("Cursor CLI installation failed or `agent` is not on PATH. Open a new terminal and re-run.");
+  }
+}
+
+async function install() {
+  requireHermes();
+  await ensureCursorCli();
+  const ref = rest.find((a) => /^[0-9a-f]{40}$/.test(a));
+  const args = ["plugins", "install", REPO, "--enable"];
+  if (ref) args.push("--ref", ref);
+  if (flags.has("--force")) args.push("--force");
+
+  console.log(`Installing ${PLUGIN} into Hermes...`);
+  if (run("hermes", args) !== 0) die("`hermes plugins install` failed (see output above).");
+
+  console.log("\nVerifying Cursor CLI connection...");
+  const modelsCheck = spawnSync("agent", ["models"], { encoding: "utf8" });
+  if (modelsCheck.status !== 0) {
+    console.log("\nNotice: Cursor CLI is installed but may not be signed in.");
+    console.log("Run `agent login` in your terminal to authenticate your Cursor subscription.");
+  } else {
+    console.log("✓ Cursor CLI is authenticated and active.");
+  }
+
+  console.log(`\n✓ Done! Start Hermes with your Cursor subscription:\n`);
+  console.log(`  hermes --provider cursor -m claude-opus-5-5`);
+  console.log(`  hermes --provider cursor -m composer-2.5\n`);
+  console.log(`Or select 'Cursor Subscription (ACP)' from /model inside Hermes.`);
+}
+
+function status() {
+  requireHermes();
+  console.log("Hermes: " + (which("hermes") || "not found"));
+  console.log("Cursor CLI (`agent`): " + (which("agent") || "not found"));
+  if (which("agent")) {
+    console.log("\nChecking Cursor models:");
+    run("agent", ["models"]);
+  }
+  console.log("\nHermes plugin status:");
+  process.exit(run("hermes", ["plugins", "list"]));
+}
+
+function uninstall() {
+  requireHermes();
+  process.exit(run("hermes", ["plugins", "remove", PLUGIN]));
+}
+
+function help() {
+  console.log(`hermes-cursor-acp — Cursor Subscription models for Hermes Agent
+
+Usage: npx hermes-cursor-acp [command] [flags]
+
+Commands:
+  install     Install + enable the Hermes plugin, verify Cursor CLI (default)
+  status      Show CLI and plugin status
+  uninstall   Remove the plugin from Hermes
+
+Flags:
+  --yes, -y      Install the Cursor CLI automatically if missing
+  --force        Reinstall over an existing copy
+  <40-hex sha>   Pin the plugin to an exact commit
+
+Platform: ${os.platform()} ${os.arch()}`);
+}
+
+const commands = { install, status, uninstall, help, "--help": help, "-h": help };
+Promise.resolve((commands[cmd] || (() => { help(); process.exit(2); }))()).catch((err) => die(err.message || String(err)));

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "hermes-cursor-acp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "One-command Cursor subscription models for Hermes Agent: installs the cursor-acp provider plugin and verifies the Cursor CLI ACP server.",
+  "bin": {
+    "hermes-cursor-acp": "bin/cli.js"
+  },
+  "files": [
+    "bin/cli.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "hermes",
+    "hermes-agent",
+    "hermes-plugin",
+    "cursor",
+    "acp",
+    "claude",
+    "composer",
+    "gpt"
+  ],
+  "author": "Neeraj Kumar Singh Beshane (https://github.com/neerazz)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neerazz/hermes-cursor-acp.git"
+  },
+  "homepage": "https://github.com/neerazz/hermes-cursor-acp#readme",
+  "bugs": "https://github.com/neerazz/hermes-cursor-acp/issues"
+}