agentsw 0.7.0 → 0.7.2

package/dist/targets/codex.js

@@ -2,6 +2,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import { backupFile, home, readJsonIfExists, readTextIfExists, writeFileAtomic } from "../fsutil.js";
+import { isJsonObject } from "../jsonc.js";
+import { transactionalTarget } from "../target-transaction.js";
 const dir = path.join(home, ".codex");
 const configFile = path.join(dir, "config.toml");
 const authFile = path.join(dir, "auth.json");
@@ -10,7 +12,7 @@ const authFile = path.join(dir, "auth.json");
  * OpenAI-protocol endpoint; the key ships via ~/.codex/auth.json OPENAI_API_KEY.
  * TOML round-trip via smol-toml preserves data but not comments (backed up first).
  */
-export const codex = {
+export const codex = transactionalTarget({
     id: "codex",
     name: "Codex CLI",
     protocols: ["openai"],
@@ -20,6 +22,13 @@ export const codex = {
         const notes = [];
         const text = readTextIfExists(configFile);
         const config = (text ? parseToml(text) : {});
+        const authValue = readJsonIfExists(authFile);
+        const auth = authValue === undefined ? {} : authValue;
+        if (!isJsonObject(auth))
+            throw new Error(`${authFile}: expected a JSON object`);
+        if (config.model_providers !== undefined && !isJsonObject(config.model_providers)) {
+            throw new Error(`${configFile}: expected model_providers to be a table`);
+        }
         config.model_provider = provider.id;
         config.model = provider.defaultModel;
         const model = provider.models.find((m) => m.id === provider.defaultModel);
@@ -29,7 +38,27 @@ export const codex = {
         // Codex only speaks the OpenAI Responses API (wire_api = "chat" was removed Feb 2026).
         // requires_openai_auth = true makes Codex take the key from auth.json instead of an env var.
         const providers = (config.model_providers ?? {});
+        const previous = providers[provider.id];
+        if (previous !== undefined && !isJsonObject(previous)) {
+            throw new Error(`${configFile}: expected the selected model provider to be a table`);
+        }
+        const kept = { ...previous };
+        for (const key of ["env_key", "env_key_instructions", "experimental_bearer_token"])
+            delete kept[key];
+        for (const key of ["http_headers", "env_http_headers"]) {
+            if (kept[key] === undefined)
+                continue;
+            if (!isJsonObject(kept[key]))
+                throw new Error(`${configFile}: expected ${key} to be a table`);
+            const headers = { ...kept[key] };
+            for (const name of Object.keys(headers)) {
+                if (["authorization", "x-api-key", "api-key"].includes(name.toLowerCase()))
+                    delete headers[name];
+            }
+            kept[key] = headers;
+        }
         providers[provider.id] = {
+            ...kept,
             name: provider.name,
             base_url: provider.baseUrl.replace(/\/$/, ""),
             wire_api: "responses",
@@ -43,7 +72,6 @@ export const codex = {
         if (text?.includes("#"))
             notes.push("config.toml comments are not preserved by TOML round-trip");
         writeFileAtomic(configFile, stringifyToml(config) + "\n");
-        const auth = readJsonIfExists(authFile) ?? {};
         auth.auth_mode = "apikey";
         auth.OPENAI_API_KEY = provider.apiKey;
         const authBackup = backupFile(authFile);
@@ -57,6 +85,9 @@ export const codex = {
         if (!text)
             return { app: this.id, changed: [], notes: [], skipped: "no config.toml" };
         const config = parseToml(text);
+        if (config.model_providers !== undefined && !isJsonObject(config.model_providers)) {
+            throw new Error(`${configFile}: expected model_providers to be a table`);
+        }
         const providers = config.model_providers;
         if (!providers?.[provider.id]) {
             return { app: this.id, changed: [], notes: [], skipped: `no model_providers.${provider.id} entry` };
@@ -133,4 +164,4 @@ export const codex = {
             ];
         });
     },
-};
+});

package/dist/targets/dsh.js

@@ -2,6 +2,9 @@ import fs from "node:fs";
 import path from "node:path";
 import YAML from "yaml";
 import { backupFile, expandHome, home, localAppDataDir, readTextIfExists, writeFileAtomic } from "../fsutil.js";
+import { isManagedCredentialRef, legacyManagedCredentialRef, managedCredentialRef } from "../provider-identity.js";
+import { transactionalTarget } from "../target-transaction.js";
+import { parseYamlMapping, serializeYamlMapping } from "../yaml.js";
 import { apiValue, classifyApi, mergeModels, sdkBaseUrl } from "./wire.js";
 /** `$DSH_HOME`, or `~/.dsh` (packages/util/home-paths `resolveDshHome`). */
 function dshHome() {
@@ -24,8 +27,6 @@ function settingsFile() {
 const credentialsFile = () => path.join(dshHome(), ".credentials.yaml");
 /** Layout version of `.credentials.yaml` this build reads and writes. */
 const CREDENTIALS_VERSION = 1;
-/** Credential reference: a POSIX identifier (`/^[A-Za-z_][A-Za-z0-9_]*$/`). */
-const credentialRef = (id) => `AGENTSW_${id.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`;
 /** Thinking levels a `reasoningEfforts` entry may offer (llm-pi-ai THINKING_LEVEL_GATE). */
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
 /** Per-model keys this adapter writes; one that stops being emitted is cleared, not inherited. */
@@ -56,25 +57,28 @@ function modelEntry(m) {
     };
 }
 function parseSettings(file) {
-    const text = readTextIfExists(file);
-    const doc = text ? YAML.parseDocument(text) : new YAML.Document({});
-    if (doc.errors.length) {
-        throw new Error(`${file} has settings errors; refusing to rewrite: ${doc.errors[0]?.message}`);
+    const doc = parseYamlMapping(file, readTextIfExists(file));
+    for (const at of [["llm-pi-ai"], ["llm-pi-ai", "providers"], ["agent-default-model"]]) {
+        if (doc.hasIn(at) && !YAML.isMap(doc.getIn(at)))
+            throw new Error(`${file}: expected ${at.join(".")} to be a mapping`);
+    }
+    const providers = doc.getIn(["llm-pi-ai", "providers"]);
+    if (YAML.isMap(providers) && providers.items.some((pair) => !YAML.isMap(pair.value))) {
+        throw new Error(`${file}: expected provider mappings`);
     }
-    if (doc.contents == null)
-        doc.contents = doc.createNode({});
     return doc;
 }
 /** JSON documents re-serialize without comments; YAML keeps them (dsh reads both). */
 function renderSettings(file, doc) {
-    return file.endsWith(".json") ? JSON.stringify(doc.toJSON(), null, 2) + "\n" : doc.toString();
+    const text = serializeYamlMapping(file, doc);
+    return file.endsWith(".json") ? JSON.stringify(doc.toJS(), null, 2) + "\n" : text;
 }
 /**
  * DeepSeek Harness (dsh): provider routes live in the `llm-pi-ai` section of
  * `$DSH_HOME/settings.yaml`, the picked default in `agent-default-model`, and
  * the key in `$DSH_HOME/.credentials.yaml` — settings carry only a reference.
  */
-export const dsh = {
+export const dsh = transactionalTarget({
     id: "dsh",
     name: "DeepSeek Harness",
     protocols: ["openai", "anthropic"],
@@ -86,22 +90,42 @@ export const dsh = {
         const doc = parseSettings(file);
         const at = ["llm-pi-ai", "providers", provider.id];
         const prev = doc.getIn(at)?.toJSON?.();
-        const ref = credentialRef(provider.id);
+        const ref = managedCredentialRef(provider.id);
         const entry = {
             displayName: provider.name,
             apiKeyEnv: ref, // credential reference, never the secret
             api: apiValue(provider.protocol, provider.openaiApi, prev?.api),
             baseURL: sdkBaseUrl(provider.protocol, provider.baseUrl),
-            models: mergeModels(prev?.models, provider.models.map(modelEntry), OWNED_MODEL_KEYS),
         };
         if (YAML.isMap(doc.getIn(at))) {
             // Key-by-key: compat, headers, defaultInput, retryPolicy and their comments are the user's.
             for (const [key, value] of Object.entries(entry))
-                doc.setIn([...at, key], doc.createNode(value));
+                doc.setIn([...at, key], value);
         }
         else {
             doc.setIn(at, doc.createNode(entry));
         }
+        const modelsAt = [...at, "models"];
+        const previousModels = doc.getIn(modelsAt);
+        const models = YAML.isSeq(previousModels) ? previousModels : doc.createNode([]);
+        const previousById = new Map();
+        for (const node of models.items) {
+            if (YAML.isMap(node))
+                previousById.set(node.get("id"), node);
+        }
+        models.items = mergeModels(prev?.models, provider.models.map(modelEntry), OWNED_MODEL_KEYS).map((model) => {
+            const node = previousById.get(model.id);
+            if (!node)
+                return doc.createNode(model);
+            for (const key of OWNED_MODEL_KEYS) {
+                if (!(key in model))
+                    node.delete(key);
+                else
+                    node.set(key, typeof model[key] === "object" ? doc.createNode(model[key]) : model[key]);
+            }
+            return node;
+        });
+        doc.setIn(modelsAt, models);
         if (doc.hasIn([...at, "modelOverrides"])) {
             // llm-pi-ai refuses modelOverrides beside an explicit models list.
             doc.deleteIn([...at, "modelOverrides"]);
@@ -109,30 +133,37 @@ export const dsh = {
         }
         // The picker writes this section whole; a partial write would keep a stale reasoningEffort.
         doc.set("agent-default-model", doc.createNode({ provider: provider.id, model: provider.defaultModel }));
+        const referenced = credentialReferences(doc, provider.id);
+        const oldRef = typeof prev?.apiKeyEnv === "string" && isManagedCredentialRef(prev.apiKeyEnv, provider.id) && !referenced.has(prev.apiKeyEnv)
+            ? prev.apiKeyEnv : undefined;
+        const credential = writeCredential(ref, provider.apiKey, notes, oldRef, referenced);
         const backup = backupFile(file);
         if (backup)
             notes.push(`backup: ${backup}`);
         writeFileAtomic(file, renderSettings(file, doc));
-        const changed = [file, writeCredential(ref, provider.apiKey, notes)];
+        const changed = [file, credential];
         notes.push(`select in dsh with the model picker, or run: dsh web`);
         return { app: this.id, changed, notes };
     },
     async prune(provider) {
         const notes = [];
-        // The stored key is removed even when the route is already gone, so a hand-deleted
-        // route never leaves its secret behind.
-        const droppedCredential = deleteCredential(credentialRef(provider.id), notes);
         const file = settingsFile();
-        const doc = fs.existsSync(file) ? parseSettings(file) : undefined;
+        // Settings must be understood before any credential can be removed.
+        const doc = parseSettings(file);
         const at = ["llm-pi-ai", "providers", provider.id];
-        if (!doc?.hasIn(at)) {
-            const why = doc ? `no llm-pi-ai.providers.${provider.id} entry` : "no settings document";
+        const hasProvider = doc.hasIn(at);
+        if (hasProvider)
+            doc.deleteIn(at);
+        const referenced = credentialReferences(doc);
+        const removable = new Set([managedCredentialRef(provider.id), legacyManagedCredentialRef(provider.id)].filter((ref) => !referenced.has(ref)));
+        const droppedCredential = deleteCredentials(removable, notes);
+        if (!hasProvider) {
+            const why = `no llm-pi-ai.providers.${provider.id} entry`;
             if (!droppedCredential)
                 return { app: this.id, changed: [], notes, skipped: why };
             notes.push(why);
             return { app: this.id, changed: [droppedCredential], notes };
         }
-        doc.deleteIn(at);
         if (doc.getIn(["agent-default-model", "provider"]) === provider.id) {
             doc.delete("agent-default-model");
             notes.push("default model selection reset (was pointing at this provider)");
@@ -147,10 +178,7 @@ export const dsh = {
         if (backup)
             notes.push(`backup: ${backup}`);
         writeFileAtomic(file, renderSettings(file, doc));
-        const changed = [file];
-        if (droppedCredential)
-            changed.push(droppedCredential);
-        return { app: this.id, changed, notes };
+        return { app: this.id, changed: droppedCredential ? [file, droppedCredential] : [file], notes };
     },
     current() {
         const text = readTextIfExists(settingsFile());
@@ -215,34 +243,38 @@ export const dsh = {
             ];
         });
     },
-};
+});
 /** Read the managed store's `refs` section; an unreadable document yields no keys. */
 function readCredentialRefs() {
-    const text = readTextIfExists(credentialsFile());
-    if (!text)
-        return {};
     try {
-        const parsed = YAML.parse(text);
-        const refs = parsed?.refs;
-        if (refs && typeof refs === "object")
-            return refs;
-        // pre-release flat layout: top-level reference-to-secret mapping
-        if (parsed && !("version" in parsed))
-            return parsed;
-        return {};
+        const doc = parseCredentials(credentialsFile());
+        const parsed = doc.toJS();
+        return (doc.get("version") === undefined ? parsed : parsed.refs ?? {});
     }
     catch {
         return {};
     }
 }
 function parseCredentials(file) {
-    const text = readTextIfExists(file);
-    const doc = text ? YAML.parseDocument(text) : new YAML.Document({});
-    if (doc.errors.length) {
-        throw new Error(`${file} has YAML errors; refusing to rewrite: ${doc.errors[0]?.message}`);
+    const doc = parseYamlMapping(file, readTextIfExists(file));
+    const version = doc.get("version");
+    if (version !== undefined && version !== CREDENTIALS_VERSION) {
+        const label = typeof version === "number" ? String(version) : "an unsupported value";
+        throw new Error(`${file} declares version ${label}; agentsw writes version ${CREDENTIALS_VERSION}`);
+    }
+    if (version === undefined) {
+        const flat = Object.entries(doc.toJS()).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === "string" && value.length > 0);
+        if (!flat)
+            throw new Error(`${file} is neither the version ${CREDENTIALS_VERSION} layout nor a pre-release flat document; refusing to rewrite it`);
+    }
+    else if (doc.has("refs") && !YAML.isMap(doc.get("refs"))) {
+        throw new Error(`${file}: expected refs to be a mapping`);
+    }
+    const refs = doc.get("refs");
+    if (version !== undefined && YAML.isMap(refs) && refs.items.some((pair) => !YAML.isScalar(pair.key) || typeof pair.key.value !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(pair.key.value) ||
+        !YAML.isScalar(pair.value) || typeof pair.value.value !== "string" || pair.value.value.length === 0)) {
+        throw new Error(`${file}: expected non-empty credential values with valid reference names`);
     }
-    if (doc.contents == null)
-        doc.contents = doc.createNode({});
     return doc;
 }
 /**
@@ -252,45 +284,65 @@ function parseCredentials(file) {
  * looks unversioned (a hand-written `refs:` block, a future layout) is refused
  * instead of being re-rooted one level deeper. Returns the file.
  */
-function writeCredential(ref, apiKey, notes) {
+function writeCredential(ref, apiKey, notes, oldRef, referenced) {
     const file = credentialsFile();
     const doc = parseCredentials(file);
-    const root = (doc.toJSON() ?? {});
-    const version = root.version;
-    if (version !== undefined && version !== CREDENTIALS_VERSION) {
-        throw new Error(`${file} declares version ${JSON.stringify(version)}; agentsw writes version ${CREDENTIALS_VERSION}`);
+    if (doc.get("version") === undefined) {
+        const refs = doc.contents;
+        const migrating = YAML.isMap(refs) && refs.items.length > 0;
+        doc.contents = doc.createNode({ version: CREDENTIALS_VERSION });
+        doc.set("refs", refs);
+        if (migrating)
+            notes.push(`migrated ${file} to the version ${CREDENTIALS_VERSION} layout`);
     }
-    if (version === undefined && Object.keys(root).length > 0) {
-        const flat = Object.entries(root).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === "string" && value.length > 0);
-        if (!flat) {
-            throw new Error(`${file} is neither the version ${CREDENTIALS_VERSION} layout nor a pre-release flat document; refusing to rewrite it`);
-        }
-        doc.contents = doc.createNode({ version: CREDENTIALS_VERSION, refs: root });
-        notes.push(`migrated ${file} to the version ${CREDENTIALS_VERSION} layout`);
+    if (referenced.has(ref) && doc.getIn(["refs", ref]) !== apiKey) {
+        throw new Error(`${file}: credential reference is shared by another provider; refusing to replace it`);
     }
-    doc.set("version", CREDENTIALS_VERSION);
     doc.setIn(["refs", ref], apiKey);
+    if (oldRef && oldRef !== ref)
+        doc.deleteIn(["refs", oldRef]);
+    const text = serializeYamlMapping(file, doc);
     const backup = backupFile(file);
     if (backup)
         notes.push(`backup: ${backup}`);
     // dsh refuses a credentials document readable beyond its owner.
-    writeFileAtomic(file, doc.toString(), 0o600);
+    writeFileAtomic(file, text, 0o600);
     return file;
 }
-/** Drop this provider's reference. Returns the file when it was rewritten. */
-function deleteCredential(ref, notes) {
+/** Drop only managed references that no surviving route uses. */
+function deleteCredentials(refs, notes) {
     const file = credentialsFile();
-    const text = readTextIfExists(file);
-    if (!text)
+    if (readTextIfExists(file) === undefined)
         return undefined;
     const doc = parseCredentials(file);
-    const at = doc.hasIn(["refs", ref]) ? ["refs", ref] : doc.has(ref) ? [ref] : undefined;
-    if (!at)
+    let changed = false;
+    for (const ref of refs) {
+        const at = doc.get("version") === undefined ? [ref] : ["refs", ref];
+        if (doc.hasIn(at)) {
+            doc.deleteIn(at);
+            changed = true;
+        }
+    }
+    if (!changed)
         return undefined;
-    doc.deleteIn(at);
+    const text = serializeYamlMapping(file, doc);
     const backup = backupFile(file);
     if (backup)
         notes.push(`backup: ${backup}`);
-    writeFileAtomic(file, doc.toString(), 0o600);
+    writeFileAtomic(file, text, 0o600);
     return file;
 }
+function credentialReferences(doc, exceptId) {
+    const providers = doc.getIn(["llm-pi-ai", "providers"]);
+    const refs = new Set();
+    if (YAML.isMap(providers)) {
+        for (const pair of providers.items) {
+            if ((YAML.isScalar(pair.key) ? pair.key.value : pair.key) === exceptId)
+                continue;
+            const ref = YAML.isMap(pair.value) ? pair.value.get("apiKeyEnv") : undefined;
+            if (typeof ref === "string")
+                refs.add(ref);
+        }
+    }
+    return refs;
+}

package/dist/targets/hermes.js

@@ -2,6 +2,10 @@ import fs from "node:fs";
 import path from "node:path";
 import YAML from "yaml";
 import { backupFile, home, localAppDataDir, readTextIfExists, writeFileAtomic } from "../fsutil.js";
+import { envAssignments, removeEnvAssignments, upsertEnvAssignment } from "../envfile.js";
+import { isManagedCredentialRef, legacyManagedCredentialRef, managedCredentialRef } from "../provider-identity.js";
+import { transactionalTarget } from "../target-transaction.js";
+import { parseYamlMapping, serializeYamlMapping } from "../yaml.js";
 import { sdkBaseUrl } from "./wire.js";
 function hermesHome() {
     const env = process.env.HERMES_HOME?.trim();
@@ -12,12 +16,45 @@ function hermesHome() {
     }
     return path.join(home, ".hermes");
 }
+function parseConfig(file, text) {
+    const doc = parseYamlMapping(file, text);
+    for (const key of ["providers", "model"]) {
+        if (doc.has(key) && !YAML.isMap(doc.get(key)))
+            throw new Error(`${file}: expected ${key} to be a mapping`);
+    }
+    const providers = doc.get("providers");
+    if (YAML.isMap(providers)) {
+        for (const pair of providers.items) {
+            if (!YAML.isMap(pair.value))
+                throw new Error(`${file}: expected provider mappings`);
+            const models = pair.value.get("models");
+            if (models !== undefined && (!YAML.isMap(models) || models.items.some((model) => !YAML.isMap(model.value)))) {
+                throw new Error(`${file}: expected model mappings`);
+            }
+        }
+    }
+    return doc;
+}
+function credentialReferences(doc, exceptId) {
+    const refs = new Set();
+    const providers = doc.get("providers");
+    if (YAML.isMap(providers)) {
+        for (const pair of providers.items) {
+            if ((YAML.isScalar(pair.key) ? pair.key.value : pair.key) === exceptId)
+                continue;
+            const ref = YAML.isMap(pair.value) ? pair.value.get("key_env") : undefined;
+            if (typeof ref === "string")
+                refs.add(ref);
+        }
+    }
+    return refs;
+}
 /**
  * hermes (NousResearch): providers dict + model section in ~/.hermes/config.yaml,
  * API key in ~/.hermes/.env referenced via key_env. hermes refuses to load an
  * unparseable config.yaml, so we round-trip through YAML Document (comments kept).
  */
-export const hermes = {
+export const hermes = transactionalTarget({
     id: "hermes",
     name: "Hermes",
     protocols: ["openai", "anthropic"],
@@ -29,56 +66,66 @@ export const hermes = {
         const envFile = path.join(home, ".env");
         const notes = [];
         const text = readTextIfExists(configFile);
-        const doc = text ? YAML.parseDocument(text) : new YAML.Document({});
-        if (doc.errors.length) {
-            throw new Error(`${configFile} has YAML errors; refusing to rewrite: ${doc.errors[0]?.message}`);
-        }
-        if (doc.contents == null)
-            doc.contents = doc.createNode({});
-        const keyVar = `AGENTSW_${provider.id.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`;
+        const doc = parseConfig(configFile, text);
+        const keyVar = managedCredentialRef(provider.id);
         const at = ["providers", provider.id];
         const prev = doc.getIn(at)?.toJSON?.();
-        const prevModels = (prev?.models ?? {});
-        const models = {};
-        for (const m of provider.models) {
-            const old = { ...prevModels[m.id] };
-            delete old.context_length; // owned: a model that loses its size must not keep the old one
-            models[m.id] = { ...old, ...(m.contextWindow ? { context_length: m.contextWindow } : {}) };
-        }
         const entry = {
             name: provider.name,
             api: sdkBaseUrl(provider.protocol, provider.baseUrl),
             key_env: keyVar,
             transport: provider.protocol === "anthropic"
                 ? "anthropic_messages"
-                : provider.openaiApi === "responses"
+                : provider.openaiApi === "responses" || (provider.openaiApi === undefined && prev?.transport === "codex_responses")
                     ? "codex_responses"
                     : "chat_completions",
             default_model: provider.defaultModel,
-            models,
         };
         // Key-by-key when the route exists: provider-level keys agentsw does not model
         // (and their comments) belong to the user.
         if (YAML.isMap(doc.getIn(at))) {
             for (const [key, value] of Object.entries(entry))
-                doc.setIn([...at, key], doc.createNode(value));
+                doc.setIn([...at, key], value);
         }
         else {
             doc.setIn(at, doc.createNode(entry));
         }
+        const modelsAt = [...at, "models"];
+        if (!doc.hasIn(modelsAt))
+            doc.setIn(modelsAt, doc.createNode({}));
+        const models = doc.getIn(modelsAt);
+        const modelIds = new Set(provider.models.map((model) => model.id));
+        for (const pair of [...models.items]) {
+            if (YAML.isScalar(pair.key) && !modelIds.has(String(pair.key.value)))
+                models.delete(pair.key.value);
+        }
+        for (const model of provider.models) {
+            const modelAt = [...modelsAt, model.id];
+            if (!doc.hasIn(modelAt))
+                doc.setIn(modelAt, doc.createNode({}));
+            if (model.contextWindow)
+                doc.setIn([...modelAt, "context_length"], model.contextWindow);
+            else
+                doc.deleteIn([...modelAt, "context_length"]);
+        }
         doc.setIn(["model", "provider"], provider.id);
         doc.setIn(["model", "default"], provider.defaultModel);
+        const envText = readTextIfExists(envFile) ?? "";
+        const assignments = envAssignments(envFile, envText);
+        const referenced = credentialReferences(doc, provider.id);
+        if (referenced.has(keyVar) && assignments.filter((assignment) => assignment.name === keyVar).at(-1)?.value !== provider.apiKey) {
+            throw new Error(`${envFile}: credential reference is shared by another provider; refusing to replace it`);
+        }
+        let nextEnv = upsertEnvAssignment(envFile, envText, keyVar, provider.apiKey);
+        const oldRef = prev?.key_env;
+        if (typeof oldRef === "string" && oldRef !== keyVar && isManagedCredentialRef(oldRef, provider.id) && !referenced.has(oldRef)) {
+            nextEnv = removeEnvAssignments(envFile, nextEnv, new Set([oldRef]));
+        }
+        const nextConfig = serializeYamlMapping(configFile, doc);
         const configBackup = backupFile(configFile);
         if (configBackup)
             notes.push(`backup: ${configBackup}`);
-        writeFileAtomic(configFile, doc.toString());
-        // upsert the key into ~/.hermes/.env
-        const envText = readTextIfExists(envFile) ?? "";
-        const line = `${keyVar}=${provider.apiKey}`;
-        const pattern = new RegExp(`^${keyVar}=.*$`, "m");
-        const nextEnv = pattern.test(envText)
-            ? envText.replace(pattern, line)
-            : envText + (envText.endsWith("\n") || envText === "" ? "" : "\n") + line + "\n";
+        writeFileAtomic(configFile, nextConfig);
         const envBackup = backupFile(envFile);
         if (envBackup)
             notes.push(`backup: ${envBackup}`);
@@ -89,18 +136,12 @@ export const hermes = {
         const home = hermesHome();
         const configFile = path.join(home, "config.yaml");
         const envFile = path.join(home, ".env");
-        const text = readTextIfExists(configFile);
-        if (!text)
-            return { app: this.id, changed: [], notes: [], skipped: "no config.yaml" };
-        const doc = YAML.parseDocument(text);
-        if (doc.errors.length) {
-            throw new Error(`${configFile} has YAML errors; refusing to rewrite: ${doc.errors[0]?.message}`);
-        }
-        if (!doc.hasIn(["providers", provider.id])) {
-            return { app: this.id, changed: [], notes: [], skipped: `no providers.${provider.id} entry` };
-        }
-        doc.deleteIn(["providers", provider.id]);
+        const doc = parseConfig(configFile, readTextIfExists(configFile));
+        const at = ["providers", provider.id];
+        const hasProvider = doc.hasIn(at);
         const notes = [];
+        if (hasProvider)
+            doc.deleteIn(at);
         if (doc.getIn(["model", "provider"]) === provider.id) {
             doc.deleteIn(["model", "provider"]);
             doc.deleteIn(["model", "default"]);
@@ -112,21 +153,27 @@ export const hermes = {
             if (YAML.isMap(node) && node.items.length === 0)
                 doc.delete(key);
         }
-        const changed = [configFile];
-        const configBackup = backupFile(configFile);
-        if (configBackup)
-            notes.push(`backup: ${configBackup}`);
-        writeFileAtomic(configFile, doc.toString());
-        const keyVar = `AGENTSW_${provider.id.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`;
+        const referenced = credentialReferences(doc);
+        const removable = new Set([managedCredentialRef(provider.id), legacyManagedCredentialRef(provider.id)].filter((ref) => !referenced.has(ref)));
         const envText = readTextIfExists(envFile);
-        if (envText && new RegExp(`^${keyVar}=`, "m").test(envText)) {
+        const nextEnv = envText === undefined ? undefined : removeEnvAssignments(envFile, envText, removable);
+        const changed = [];
+        if (hasProvider) {
+            const config = serializeYamlMapping(configFile, doc);
+            const configBackup = backupFile(configFile);
+            if (configBackup)
+                notes.push(`backup: ${configBackup}`);
+            writeFileAtomic(configFile, config);
+            changed.push(configFile);
+        }
+        if (nextEnv !== undefined && nextEnv !== envText) {
             const envBackup = backupFile(envFile);
             if (envBackup)
                 notes.push(`backup: ${envBackup}`);
-            writeFileAtomic(envFile, envText.replace(new RegExp(`^${keyVar}=.*\\n?`, "m"), ""), 0o600);
+            writeFileAtomic(envFile, nextEnv, 0o600);
             changed.push(envFile);
         }
-        return { app: this.id, changed, notes };
+        return changed.length ? { app: this.id, changed, notes } : { app: this.id, changed, notes, skipped: `no providers.${provider.id} entry or managed credential` };
     },
     current() {
         const text = readTextIfExists(path.join(hermesHome(), "config.yaml"));
@@ -156,8 +203,10 @@ export const hermes = {
         }
         if (!parsed?.providers)
             return [];
-        const envText = readTextIfExists(path.join(hh, ".env")) ?? "";
-        const readEnv = (key) => process.env[key] ?? (envText.match(new RegExp(`^${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}=(.*)$`, "m"))?.[1]?.trim() || undefined);
+        const envFile = path.join(hh, ".env");
+        const envText = readTextIfExists(envFile) ?? "";
+        const values = new Map(envAssignments(envFile, envText).map((assignment) => [assignment.name, assignment.value]));
+        const readEnv = (key) => process.env[key] ?? values.get(key);
         const self = this.id;
         return Object.entries(parsed.providers).flatMap(([id, entry]) => {
             if (!entry || typeof entry.api !== "string" || !entry.api)
@@ -180,4 +229,4 @@ export const hermes = {
             return [{ id, name: entry.name ?? id, protocol, openaiApi, baseUrl: entry.api, apiKey, keyEnv, models, defaultModel, source: self }];
         });
     },
-};
+});