Skip to content

Every agent's model. One place. Codex on DeepSeek, Claude Code on Kimi, from the menu bar.

agent: Hermes's api_key as "${VAR}" with the key in its .env reaches magpie (PaulT on Discord)

yetoneb9d1cd36f5e9
diff --git a/docs/subsystems/agent-wiring.md b/docs/subsystems/agent-wiring.md
index 286f46493..1d836f1e1 100644
--- a/docs/subsystems/agent-wiring.md
+++ b/docs/subsystems/agent-wiring.md
@@ -48,6 +48,7 @@ something else shows up as drift.
- Qoder's `providers.magpie` keeps `routing`, the timeouts, `type`, `authType`, `anthropic` and a non-empty `displayName` (`qoderKept`).
- fx keeps `reviewer_model` and a `tool_choice_mode` of `omit`. Its `auth` is magpie's whole, since fx refuses an `env` beside `type: none` (`fxKept`).
- Hermes keeps the `default_model` that `hermes model` writes there, `key_cmd`, the timeouts, `extra_body`, a name and headers beside magpie's (`hermesKept`). This holds in every profile.
+ - Hermes's `api_key` may be a reference, `${VAR}` or `${env:VAR}`, which Hermes expands from the `.env` beside the config (its own or a profile's) and then the environment. `Check` and a sync read the key it names (`hermesKey`): one that holds (`keyHolds`) stays and isn't drift, and so does one naming a variable magpie can't see (only a shell profile sets it), which is unknown. One naming a key the gateway doesn't take is drift, and a sync keeps the reference and writes magpie's key into that `.env` under the variable, made `0600` when there is none (`hermesKeptKey`; PaulT on Discord, `TestHermesWithAKeyInItsEnvFile`). A value with more than the one reference in it is replaced by magpie's key, as before.
- omp's `models.yml` keeps `modelOverrides`, `discovery`, `disableStrictTools`, headers and compat flags (`ompKept`). Its `auth` and `apiKey` are magpie's, or gone.
- Kimi Code's `[providers.magpie]` has magpie's three keys set in place, so `custom_headers`, `env` and `default_model` stay (`kimiProvider`).
- Cline's `models.json` keeps the provider's other keys, and on each model magpie lists what magpie doesn't write, such as a VS Code override (`clineKept`).
diff --git a/internal/agent/hermes.go b/internal/agent/hermes.go
index 05517a03c..b1bd7a73c 100644
--- a/internal/agent/hermes.go
+++ b/internal/agent/hermes.go
@@ -29,6 +29,7 @@ import (
"regexp"
"strings"
+ "github.com/yetone/magpie/internal/appdir"
"github.com/yetone/magpie/internal/dirent"
"github.com/yetone/magpie/internal/edit"
)
@@ -41,7 +42,7 @@ func hermes(home string) *Agent { return hermesIn(here(home)) }
func hermesIn(at place) *Agent {
dir := at.hermesHome()
path := filepath.Join(dir, "config.yaml")
- hermesProvider := func(p string) any { return hermesKept(p, hermesProviderAt(at.gw())) }
+ hermesProvider := func(p string) any { return hermesKept(at, p, hermesProviderAt(at.gw())) }
// spread puts magpie's provider, as it is now, into every other
// profile's config beside the one magpie connects
spread := func() error {
@@ -116,8 +117,23 @@ func hermesIn(at place) *Agent {
if !onMagpie() {
return ""
}
- return wiringOff("Hermes", path, func(k string) (string, bool) { return edit.GetYAML(path, "providers."+magpieID+"."+k) },
- "base_url", at.v1(), "api_key", at.gwKey())
+ get := func(k string) (string, bool) {
+ v, ok := edit.GetYAML(path, "providers."+magpieID+"."+k)
+ if k != "api_key" || !hermesEnvRef.MatchString(v) {
+ return v, ok
+ }
+ // a reference to a variable: the key it names, as Hermes
+ // reads it (PaulT on Discord: "${MAGPIE_API_KEY}" with the
+ // key in Hermes's .env was said not to reach magpie). One
+ // magpie can't see (a variable of the shell's alone) is
+ // unknown, never drift.
+ key, known := hermesKey(at, path, v)
+ if !known {
+ return at.gwKey(), true
+ }
+ return key, true
+ }
+ return wiringOff("Hermes", path, get, "base_url", at.v1(), "api_key", at.gwKey())
},
Fields: []Field{{
Key: "model", Label: "model",
@@ -284,14 +300,102 @@ func hermesProviderAt(gw string) hermesProviderEntry {
// key_cmd, request_timeout_seconds, extra_body, context_length, enabled or
// ssl_* (hermes_cli/config_providers.py _KNOWN_PROVIDER_KEYS). Each stays,
// as does a name of their own and a header beside magpie's User-Agent; the
-// address, key, API mode and model list are magpie's (#2030).
-func hermesKept(path string, e hermesProviderEntry) any {
+// address, key, API mode and model list are magpie's (#2030), but for a
+// key the user keeps as a reference to a variable (hermesKeptKey).
+func hermesKept(at place, path string, e hermesProviderEntry) any {
+ e.APIKey = hermesKeptKey(at, path, e.APIKey)
if name, ok := edit.GetYAML(path, "providers."+magpieID+".name"); ok && strings.TrimSpace(name) != "" {
e.Name = name
}
return yamlKept(path, "providers."+magpieID, e, "base_url", "api_key", "api_mode", "models")
}
+// hermesEnvRef is a reference in a value of Hermes's config.yaml, which
+// Hermes expands as it loads it: ${VAR}, or ${env:VAR}
+// (hermes_cli/config.py _ENV_REF_RE, _env_expand_match).
+var hermesEnvRef = regexp.MustCompile(`\$\{([^}]+)\}`)
+
+// hermesSecretSource starts a reference to a secret source other than the
+// environment (${vault:...}, ${bitwarden:...}), which Hermes leaves as it
+// is in config.yaml (_is_non_env_secret_ref).
+var hermesSecretSource = regexp.MustCompile(`^[a-z][a-z0-9_-]*:`)
+
+// hermesRefVar is the variable the body of a reference reads, "" for
+// another source or an empty ${env:} (_env_ref_var_name).
+func hermesRefVar(body string) string {
+ body = strings.TrimSpace(body)
+ if v, ok := strings.CutPrefix(body, "env:"); ok {
+ return strings.TrimSpace(v)
+ }
+ if hermesSecretSource.MatchString(body) {
+ return ""
+ }
+ return body
+}
+
+// hermesEnvFile is the .env beside the config at path, Hermes's or a
+// profile's own, where Hermes keeps keys (load_hermes_dotenv).
+func hermesEnvFile(path string) string { return filepath.Join(filepath.Dir(path), ".env") }
+
+// hermesKey is the api_key v in the config at path as Hermes sends it, each
+// reference expanded: from the .env beside it, which Hermes loads over its
+// environment, then from the environment, this machine's only. known is
+// false when a reference names a variable magpie can't see there (one only
+// a shell profile sets) or another source; Hermes would expand it, or send
+// it as it is, and magpie can't tell which.
+func hermesKey(at place, path, v string) (key string, known bool) {
+ known = true
+ key = hermesEnvRef.ReplaceAllStringFunc(v, func(ref string) string {
+ name := hermesRefVar(ref[2 : len(ref)-1])
+ if name == "" {
+ known = false
+ return ref
+ }
+ if val, ok := edit.GetEnvFile(hermesEnvFile(path), name); ok {
+ return val
+ }
+ if at.spell == nil {
+ if val, ok := appdir.LookupEnv(name); ok {
+ return val
+ }
+ }
+ known = false
+ return ref
+ })
+ return key, known
+}
+
+// hermesKeptKey is the api_key magpie writes into the config at path, where
+// want is its own key: a reference the user put there stays, whenever the
+// key it names holds (keyHolds) or magpie can't see it. One naming a key
+// the gateway doesn't take stays too, and magpie's key goes into the .env
+// beside the config under its variable, which Hermes reads over the
+// environment; a value with more than the one reference in it is magpie's
+// key again.
+func hermesKeptKey(at place, path, want string) string {
+ raw, _ := edit.GetYAML(path, "providers."+magpieID+".api_key")
+ if !hermesEnvRef.MatchString(raw) {
+ return want
+ }
+ if key, known := hermesKey(at, path, raw); !known || keyHolds(key, want) {
+ return raw
+ }
+ m := hermesEnvRef.FindStringSubmatch(raw)
+ name := hermesRefVar(m[1])
+ if m[0] != strings.TrimSpace(raw) || name == "" {
+ return want
+ }
+ // a .env made here holds a key, so only its owner reads it, as
+ // Hermes writes its own (_write_env_lines)
+ if f, err := os.OpenFile(hermesEnvFile(path), os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600); err == nil {
+ f.Close()
+ }
+ if edit.SetEnvFile(hermesEnvFile(path), edit.KV{Path: name, Value: want}) != nil {
+ return want
+ }
+ return raw
+}
+
// what hermes says after a change (notice.go)
var (
noticeHermes = newNotice("Hermes reads its settings at start-up — restart open Hermes sessions to use this.")
diff --git a/internal/agent/hermes_test.go b/internal/agent/hermes_test.go
index cfba910f0..495db7e2f 100644
--- a/internal/agent/hermes_test.go
+++ b/internal/agent/hermes_test.go
@@ -415,6 +415,117 @@ func TestHermesWithAGatewayKeyOfTheUsers(t *testing.T) {
}
}
+// PaulT on Discord: Hermes's provider written as Hermes keeps keys, the
+// api_key "${MAGPIE_API_KEY}" with the key in Hermes's .env, was marked as
+// needing attention. A reference names the key Hermes sends: one that
+// reaches magpie is not drift and a sync keeps it; one magpie can't see is
+// unknown, kept and not drift; one naming a key the gateway doesn't take
+// is drift, and a sync puts magpie's key into the .env, the reference kept.
+func TestHermesWithAKeyInItsEnvFile(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+ t.Setenv("HERMES_HOME", "")
+ t.Setenv("XDG_CONFIG_HOME", filepath.Join(home, ".config"))
+ t.Setenv("XDG_CACHE_HOME", filepath.Join(home, ".cache"))
+ t.Setenv("MAGPIE_API_KEY", "")
+ os.Unsetenv("MAGPIE_API_KEY")
+ if err := provider.Save(provider.Provider{ID: "deepseek", Name: "DeepSeek", Chat: "https://api.deepseek.com/v1", Key: "k", Models: []string{"pro"}}); err != nil {
+ t.Fatal(err)
+ }
+ dir := appdir.HermesHomeIn(home)
+ path := filepath.Join(dir, "config.yaml")
+ env := filepath.Join(dir, ".env")
+ os.MkdirAll(dir, 0o755)
+ os.WriteFile(path, []byte("model:\n default: x\n"), 0o644)
+ a := hermes(home)
+ if err := a.Field("model").Set("magpie/deepseek/pro"); err != nil {
+ t.Fatal(err)
+ }
+ secret, err := access.Update("add-key", access.Change{Name: "hermes"})
+ if err != nil {
+ t.Fatal(err)
+ }
+ // the reporter's provider, as he wrote it
+ mine := "model:\n default: deepseek/pro\n provider: magpie\nproviders:\n magpie:\n name: magpie\n api_key: \"${MAGPIE_API_KEY}\"\n api_mode: chat_completions\n base_url: " + here(home).v1() + "\n"
+ if err := os.WriteFile(path, []byte(mine), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ ref := func(what string) {
+ t.Helper()
+ if v, _ := edit.GetYAML(path, "providers.magpie.api_key"); v != "${MAGPIE_API_KEY}" {
+ t.Fatalf("%s: the user's reference was written over: %q", what, v)
+ }
+ }
+ for _, c := range []struct{ name, line string }{
+ {"a gateway key", "MAGPIE_API_KEY=" + secret},
+ {"magpie's own key, quoted", "export MAGPIE_API_KEY=\"" + gateway.Token + "\""},
+ } {
+ os.WriteFile(env, []byte("OPENROUTER_API_KEY=sk-or\n"+c.line+"\n"), 0o600)
+ if d := a.Check(); d != "" {
+ t.Fatalf("%s in .env is drift: %s", c.name, d)
+ }
+ if err := a.Sync(); err != nil {
+ t.Fatal(err)
+ }
+ ref(c.name)
+ if err := a.Field("model").Set("magpie/deepseek/pro"); err != nil {
+ t.Fatal(err)
+ }
+ ref(c.name + ", then a pick")
+ }
+ // ${env:VAR}, Hermes's other spelling, from the environment
+ os.Remove(env)
+ if err := edit.SetYAML(path, edit.KV{Path: "providers.magpie.api_key", Value: "${env:MAGPIE_API_KEY}"}); err != nil {
+ t.Fatal(err)
+ }
+ t.Setenv("MAGPIE_API_KEY", secret)
+ if d := a.Check(); d != "" {
+ t.Fatalf("a gateway key in the environment is drift: %s", d)
+ }
+ os.Unsetenv("MAGPIE_API_KEY")
+ if err := edit.SetYAML(path, edit.KV{Path: "providers.magpie.api_key", Value: "${MAGPIE_API_KEY}"}); err != nil {
+ t.Fatal(err)
+ }
+ // a variable only the shell sets, which magpie doesn't see: unknown
+ if d := a.Check(); d != "" {
+ t.Fatalf("a variable magpie can't see is drift: %s", d)
+ }
+ if err := a.Sync(); err != nil {
+ t.Fatal(err)
+ }
+ ref("a variable magpie can't see")
+ if _, err := os.Stat(env); err == nil {
+ t.Fatal("a sync made a .env for a variable magpie can't see")
+ }
+ // a key the gateway doesn't take
+ os.WriteFile(env, []byte("# keys\nMAGPIE_API_KEY=sk-not-this-gateways\nOTHER=1\n"), 0o600)
+ if d := a.Check(); !strings.Contains(d, "api_key") {
+ t.Fatalf("a key the gateway doesn't take is not reported: %q", d)
+ }
+ if err := a.Sync(); err != nil {
+ t.Fatal(err)
+ }
+ ref("a key the gateway doesn't take")
+ b, _ := os.ReadFile(env)
+ if want := "# keys\nMAGPIE_API_KEY=" + gateway.Token + "\nOTHER=1\n"; string(b) != want {
+ t.Fatalf(".env after a sync:\n%s\nwant:\n%s", b, want)
+ }
+ if d := a.Check(); d != "" {
+ t.Fatalf("after a sync: %s", d)
+ }
+ // more than the one reference: magpie's key, as before
+ if err := edit.SetYAML(path, edit.KV{Path: "providers.magpie.api_key", Value: "x${MAGPIE_API_KEY}"}); err != nil {
+ t.Fatal(err)
+ }
+ if err := a.Sync(); err != nil {
+ t.Fatal(err)
+ }
+ if v, _ := edit.GetYAML(path, "providers.magpie.api_key"); v != gateway.Token {
+ t.Fatalf("a value that doesn't reach magpie is kept: %q", v)
+ }
+}
+
// keyHolds, which every agent's check of magpie's key goes through: a key
// of the gateway's own stands in for magpie's, never for a URL or another
// value, and one the gateway doesn't take doesn't.