@alfe.ai/integrations 0.2.1 → 0.2.3

package/dist/index.d.ts

@@ -913,9 +913,11 @@ declare class HermesApplier implements RuntimeApplier {
   readonly runtime = "hermes";
   private home;
   private trackingPath;
+  /** `~/.hermes/config.yaml` — read-merge-written on removal (no `config unset`). */
+  private configYamlPath;
   private configSetRetries;
   private configSetRetryDelayMs;
-  /** Serializes all `hermes config` writes so they never interleave. */
+  /** Serializes all config mutations (CLI `set` + config.yaml delete) so they never interleave. */
   private configSetQueue;
   constructor(options?: HermesApplierOptions);
   /**
@@ -929,8 +931,9 @@ declare class HermesApplier implements RuntimeApplier {
   /**
    * Remove config previously applied by an integration.
    *
-   * Reads the tracking file to find which keys this integration set, then
-   * removes each via `hermes config unset`. Clears the tracking entry.
+   * Reads the tracking file to find which dotted keys this integration set, then
+   * DELETES each from `~/.hermes/config.yaml` via a read-merge-write (there is no
+   * `hermes config unset` verb — see the file header). Clears the tracking entry.
    */
   removeConfig(integrationId: string): Promise<void>;
   /**
@@ -967,21 +970,25 @@ declare class HermesApplier implements RuntimeApplier {
   /** Convenience: `hermes config set <args>`, serialized + retried. */
   private runConfigSet;
   /**
-   * Unset a single config key. The unset verb is isolated HERE so there is one
-   * place to change if the spike proves `hermes config unset` is unavailable.
-   *
-   * FALLBACK (do NOT pre-build): if `hermes config unset` does not exist, the
-   * substitute is `hermes config set <key> ""` (clear the value) or a
-   * read-merge-write of config.yaml. Not implemented now — `unset` is the
-   * documented verb; confirm in the Phase-0 spike before adding a fallback.
-   * TODO(phase-0 spike): confirm `hermes config unset <key>` exists.
-   */
-  private unsetConfigKey;
-  /**
-   * Run `hermes config <args>` (set/unset), serialized against every other
-   * config write and retried with backoff. Throws an Error whose (scrubbed)
-   * message includes stderr after retries are exhausted, so the real cause
-   * propagates to the integration errorMessage without leaking the value.
+   * Delete a set of dotted config keys from `~/.hermes/config.yaml`. There is no
+   * `hermes config unset` verb (see file header), so removal is a read-merge-write
+   * of the YAML via the Document API — preserving user-authored keys, comments,
+   * and formatting. Serialized against every other config mutation on the same
+   * queue so a delete can't interleave with an in-flight `hermes config set`.
+   */
+  private deleteConfigKeys;
+  /**
+   * Synchronous config.yaml read-merge-write: parse the doc, delete each dotted
+   * key (`model.base_url` → `deleteIn(['model','base_url'])`), and write back only
+   * if the text actually changed. No-op if config.yaml doesn't exist yet.
+   */
+  private deleteConfigKeysSync;
+  /**
+   * Run `hermes config <args>` (only `set` is used — removal goes via
+   * {@link deleteConfigKeys}), serialized against every other config mutation and
+   * retried with backoff. Throws an Error whose (scrubbed) message includes stderr
+   * after retries are exhausted, so the real cause propagates to the integration
+   * errorMessage without leaking the value.
    */
   private runConfigCommand;
   private readTracking;

package/dist/index.js

@@ -1713,27 +1713,38 @@ const delay$1 = (ms) => new Promise((resolve) => {
 	setTimeout(resolve, ms);
 });
 /**
-* Structural equality for config read-back comparison. Primitives compare by
-* `Object.is`; arrays are order-SENSITIVE (config arrays are positional);
-* plain objects are order-INSENSITIVE (key order in JSON is not meaningful).
-* Used only to confirm a value landed after a `config set` exited non-zero.
+* Asymmetric structural containment for verify-after-write: is every field we
+* INTENDED present in the ACTUAL read-back with our value? `actual` may carry
+* EXTRA keys that `intended` does not.
+*
+* Verify-after-write only needs to answer "did our write land?", and OpenClaw
+* NORMALIZES config on load — most notably it enriches every
+* `models.providers.*.models` entry with schema defaults (`reasoning`, `input`,
+* `cost`, `contextWindow`, `maxTokens`, …) that the applier never wrote. A
+* strict `deepEqual` against the enriched read-back is therefore GUARANTEED to
+* fail for model lists (extra keys → unequal key counts), which strands the
+* `alfe` activation in `error` forever even though the write succeeded. A subset
+* check tolerates enrichment while still catching a genuine failure (a value
+* OpenClaw never stored, or stored differently).
+*
+* Arrays stay positional and length-EXACT (enrichment adds object fields, never
+* elements, and never reorders); each element is compared by subset. Objects
+* require every `intended` key to be present-and-subset-matching in `actual`;
+* primitives compare by `Object.is`.
 */
-function deepEqual(a, b) {
-	if (Object.is(a, b)) return true;
-	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
-	const aIsArr = Array.isArray(a);
-	const bIsArr = Array.isArray(b);
-	if (aIsArr !== bIsArr) return false;
-	if (aIsArr && bIsArr) {
-		if (a.length !== b.length) return false;
-		return a.every((v, i) => deepEqual(v, b[i]));
-	}
-	const ao = a;
-	const bo = b;
-	const aKeys = Object.keys(ao);
-	const bKeys = Object.keys(bo);
-	if (aKeys.length !== bKeys.length) return false;
-	return aKeys.every((k) => Object.prototype.hasOwnProperty.call(bo, k) && deepEqual(ao[k], bo[k]));
+function deepSubset(intended, actual) {
+	if (Object.is(intended, actual)) return true;
+	if (typeof intended !== "object" || typeof actual !== "object" || intended === null || actual === null) return false;
+	const iIsArr = Array.isArray(intended);
+	const aIsArr = Array.isArray(actual);
+	if (iIsArr !== aIsArr) return false;
+	if (iIsArr && aIsArr) {
+		if (intended.length !== actual.length) return false;
+		return intended.every((v, i) => deepSubset(v, actual[i]));
+	}
+	const io = intended;
+	const ao = actual;
+	return Object.keys(io).every((k) => Object.prototype.hasOwnProperty.call(ao, k) && deepSubset(io[k], ao[k]));
 }
 /**
 * Describe a `config set` target WITHOUT leaking values. The value argument is
@@ -1844,7 +1855,7 @@ var OpenClawApplier = class {
 			], { timeout: 1e4 });
 			const actual = JSON.parse(stdout.trim());
 			if (actual === OPENCLAW_REDACTED) return true;
-			return deepEqual(actual, expected);
+			return deepSubset(expected, actual);
 		} catch {
 			return false;
 		}
@@ -2094,7 +2105,7 @@ var OpenClawApplier = class {
 			} catch (err) {
 				if (await this.verifyApplied(async () => {
 					const after = await readParentObject(parentPath);
-					return [...dottedKvs.entries()].every(([k, v]) => deepEqual(after[k], v));
+					return [...dottedKvs.entries()].every(([k, v]) => deepSubset(v, after[k]));
 				})) {
 					log$3.warn({ parentPath }, "openclaw config set exited non-zero but config landed — continuing");
 					continue;
@@ -2193,11 +2204,17 @@ var OpenClawApplier = class {
 * HermesApplier — applies integration config (and, later, native plugins) to
 * the Hermes runtime (Nous Research's Python agent).
 *
-* Hermes config lives in `~/.hermes/config.yaml` (YAML) and is mutated via the
-* `hermes config set/unset <dotted.key> <value>` CLI — we never write the YAML
-* file directly (mirrors the OpenClaw rule of letting the runtime own its own
-* config format). Per-integration contributions are tracked in a separate file
-* (`~/.hermes/.alfe-integrations.json`) so removal is precise.
+* Hermes config lives in `~/.hermes/config.yaml` (YAML). We APPLY config via the
+* `hermes config set <dotted.key> <value>` CLI (letting the runtime own its
+* write path, mirroring the OpenClaw rule). REMOVAL is different: `hermes config
+* unset` does NOT exist — CONFIRMED against Hermes source, whose `config`
+* subcommands are only show/set/edit/path/env-path/check/migrate. So teardown is
+* a config.yaml read-merge-write that deletes the Alfe-applied dotted keys via
+* the `yaml` Document API (`parseDocument` + `deleteIn`), preserving
+* user-authored keys, comments, and formatting (the same approach
+* `hermes-mcp-sync.ts` uses for `mcp_servers`). Per-integration contributions are
+* tracked in a separate file (`~/.hermes/.alfe-integrations.json`) so we know
+* exactly which keys to delete.
 *
 * Scope (Phase 1, MCP-first hybrid):
 *  - config: SUPPORTED — consumes `installs.runtimes.hermes.config` (the AI-proxy
@@ -2243,9 +2260,9 @@ function stringifyConfigValue(value) {
 	return typeof value === "string" ? value : JSON.stringify(value);
 }
 /**
-* Describe a `config set/unset` target WITHOUT leaking values. The value
-* argument can be a secret (`model.api_key`), so it must never reach the
-* integration's user-facing `errorMessage`. Keep only the program + verb + key.
+* Describe a `config set` target WITHOUT leaking values. The value argument can
+* be a secret (`model.api_key`), so it must never reach the integration's
+* user-facing `errorMessage`. Keep only the program + verb + key.
 */
 function redactConfigTarget(args) {
 	return `hermes config ${args.slice(0, 2).join(" ")}`.trim();
@@ -2270,13 +2287,16 @@ var HermesApplier = class {
 	runtime = "hermes";
 	home;
 	trackingPath;
+	/** `~/.hermes/config.yaml` — read-merge-written on removal (no `config unset`). */
+	configYamlPath;
 	configSetRetries;
 	configSetRetryDelayMs;
-	/** Serializes all `hermes config` writes so they never interleave. */
+	/** Serializes all config mutations (CLI `set` + config.yaml delete) so they never interleave. */
 	configSetQueue = Promise.resolve();
 	constructor(options = {}) {
 		this.home = options.home ?? options.workspace ?? DEFAULT_HERMES_HOME$1;
 		this.trackingPath = options.configPath ?? join(this.home, ".alfe-integrations.json");
+		this.configYamlPath = join(this.home, "config.yaml");
 		this.configSetRetries = options.configSetRetries ?? CONFIG_SET_RETRIES;
 		this.configSetRetryDelayMs = options.configSetRetryDelayMs ?? CONFIG_SET_RETRY_DELAY_MS;
 	}
@@ -2311,8 +2331,9 @@ var HermesApplier = class {
 	/**
 	* Remove config previously applied by an integration.
 	*
-	* Reads the tracking file to find which keys this integration set, then
-	* removes each via `hermes config unset`. Clears the tracking entry.
+	* Reads the tracking file to find which dotted keys this integration set, then
+	* DELETES each from `~/.hermes/config.yaml` via a read-merge-write (there is no
+	* `hermes config unset` verb — see the file header). Clears the tracking entry.
 	*/
 	async removeConfig(integrationId) {
 		const tracking = this.readTracking();
@@ -2320,13 +2341,13 @@ var HermesApplier = class {
 		if (!(integrationId in integrations)) return;
 		const integrationConfig = integrations[integrationId];
 		const { leaves } = partitionEntries(flattenConfig(integrationConfig));
-		for (const { path } of leaves) try {
-			await this.unsetConfigKey(path);
+		try {
+			await this.deleteConfigKeys(leaves.map(({ path }) => path));
 		} catch (err) {
 			log$2.warn({
 				err: err instanceof Error ? err.message : String(err),
-				key: path
-			}, "Failed to unset config via hermes config unset");
+				integrationId
+			}, "Failed to delete Alfe config keys from ~/.hermes/config.yaml");
 		}
 		tracking._integrations = Object.fromEntries(Object.entries(integrations).filter(([key]) => key !== integrationId));
 		this.writeTracking(tracking);
@@ -2410,23 +2431,40 @@ var HermesApplier = class {
 		return this.runConfigCommand(["set", ...setArgs]);
 	}
 	/**
-	* Unset a single config key. The unset verb is isolated HERE so there is one
-	* place to change if the spike proves `hermes config unset` is unavailable.
-	*
-	* FALLBACK (do NOT pre-build): if `hermes config unset` does not exist, the
-	* substitute is `hermes config set <key> ""` (clear the value) or a
-	* read-merge-write of config.yaml. Not implemented now — `unset` is the
-	* documented verb; confirm in the Phase-0 spike before adding a fallback.
-	* TODO(phase-0 spike): confirm `hermes config unset <key>` exists.
+	* Delete a set of dotted config keys from `~/.hermes/config.yaml`. There is no
+	* `hermes config unset` verb (see file header), so removal is a read-merge-write
+	* of the YAML via the Document API — preserving user-authored keys, comments,
+	* and formatting. Serialized against every other config mutation on the same
+	* queue so a delete can't interleave with an in-flight `hermes config set`.
+	*/
+	deleteConfigKeys(paths) {
+		const run = () => {
+			this.deleteConfigKeysSync(paths);
+			return Promise.resolve();
+		};
+		const result = this.configSetQueue.then(run, run);
+		this.configSetQueue = result.catch(() => void 0);
+		return result;
+	}
+	/**
+	* Synchronous config.yaml read-merge-write: parse the doc, delete each dotted
+	* key (`model.base_url` → `deleteIn(['model','base_url'])`), and write back only
+	* if the text actually changed. No-op if config.yaml doesn't exist yet.
 	*/
-	unsetConfigKey(key) {
-		return this.runConfigCommand(["unset", key]);
+	deleteConfigKeysSync(paths) {
+		if (paths.length === 0 || !existsSync(this.configYamlPath)) return;
+		const doc = parseDocument(readFileSync(this.configYamlPath, "utf-8"));
+		const before = doc.toString();
+		for (const path of paths) doc.deleteIn(path.split("."));
+		const after = doc.toString();
+		if (before !== after) writeFileSync(this.configYamlPath, after, "utf-8");
 	}
 	/**
-	* Run `hermes config <args>` (set/unset), serialized against every other
-	* config write and retried with backoff. Throws an Error whose (scrubbed)
-	* message includes stderr after retries are exhausted, so the real cause
-	* propagates to the integration errorMessage without leaking the value.
+	* Run `hermes config <args>` (only `set` is used — removal goes via
+	* {@link deleteConfigKeys}), serialized against every other config mutation and
+	* retried with backoff. Throws an Error whose (scrubbed) message includes stderr
+	* after retries are exhausted, so the real cause propagates to the integration
+	* errorMessage without leaking the value.
 	*/
 	runConfigCommand(args) {
 		const run = async () => {
@@ -2502,15 +2540,13 @@ var HermesApplier = class {
 const log$1 = createLogger("HermesMcpSync");
 const DEFAULT_HERMES_HOME = join(homedir(), ".hermes");
 /**
-* SPIKE-PENDING SEAM #1 — `${VAR}` interpolation from `~/.hermes/.env`.
-*
-* We inject `ALFE_API_KEY=${ALFE_API_KEY}` into every Alfe-owned stdio server's
-* env and put the real value in `~/.hermes/.env`. This assumes Hermes
-* interpolates `${VAR}` references in `mcp_servers.<id>.env` from `.env` at spawn
-* time. TODO(phase-0 spike): confirm. If Hermes does NOT interpolate, the
-* fallback (NOT built here) is to write the literal `ALFE_API_KEY` VALUE inline
-* into each `mcp_servers.<id>.env` and skip the `.env` file entirely — change
-* `withAlfeApiKey()` + `ensureEnvApiKey()` together in that one case.
+* SEAM #1 — `${VAR}` interpolation from `~/.hermes/.env`. CONFIRMED (Hermes
+* source `config.py:5790` `_expand_env_vars`): Hermes loads `~/.hermes/.env` via
+* dotenv into `os.environ`, then recursively expands `${VAR}` refs across the
+* ENTIRE merged config — including `mcp_servers.<id>.env.*` (and `model.api_key`
+* / `model.base_url`). So injecting `ALFE_API_KEY=${ALFE_API_KEY}` into every
+* Alfe-owned stdio server's env and writing the real value to `~/.hermes/.env`
+* resolves at spawn time. The inline-literal fallback is therefore not needed.
 */
 const ALFE_API_KEY_ENV_REF = "${ALFE_API_KEY}";
 const DEFAULT_DEBOUNCE_MS = 250;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/integrations",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Integration lifecycle management for Alfe — registry, resolution, installation, and state",
   "type": "module",
   "main": "./dist/index.js",