@alfe.ai/integrations 0.2.0 → 0.2.2

package/dist/index.d.ts

@@ -796,6 +796,26 @@ declare class OpenClawApplier implements RuntimeApplier {
    * without leaking the value payload.
    */
   private runConfigCommand;
+  /**
+   * Read back a single config path and compare it to the value we tried to
+   * write. Used by `applyConfig`'s verify-after-write: a `config set` can exit
+   * non-zero (a hot-reload races the write, OpenClaw's clobber protection
+   * fires) even though the value actually landed, exactly like `applyPlugin`'s
+   * install-then-check tolerance.
+   *
+   * OpenClaw REDACTS sensitive values on `config get`, returning the literal
+   * `__OPENCLAW_REDACTED__` instead of the real value. Treat that as a match:
+   * the key exists and OpenClaw is hiding it, so a deep-equal against the
+   * intended value would otherwise be a false negative and force a re-throw.
+   */
+  private configValueMatches;
+  /**
+   * Run a read-back `check` with the same retry/backoff cadence as the config
+   * writes — the settling hot-reload may still be rewriting openclaw.json when
+   * we first read back, so a single check can be a false negative. Returns true
+   * on the first success, false once all attempts are exhausted.
+   */
+  private verifyApplied;
   applyPlugin(spec: string, _installPath?: string, opts?: {
     force?: boolean;
   }): Promise<void>;
@@ -893,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);
   /**
@@ -909,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>;
   /**
@@ -947,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

@@ -1702,10 +1702,40 @@ const BUNDLED_BASELINE_ALLOW = ["browser"];
 */
 const CONFIG_SET_RETRIES$1 = 3;
 const CONFIG_SET_RETRY_DELAY_MS$1 = 750;
+/**
+* Sentinel OpenClaw returns from `config get` in place of a sensitive value —
+* the key IS set, OpenClaw is just hiding it. Verify-after-write must treat a
+* read-back of this as "present/matches" rather than a mismatch (see
+* `configValueMatches`).
+*/
+const OPENCLAW_REDACTED = "__OPENCLAW_REDACTED__";
 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.
+*/
+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]));
+}
+/**
 * Describe a `config set` target WITHOUT leaking values. The value argument is
 * the JSON payload (model config, the gateway loopback token via the alfe hook,
 * etc.) and must never reach the integration's `errorMessage`, which projects
@@ -1793,6 +1823,45 @@ var OpenClawApplier = class {
 		this.configSetQueue = result.catch(() => void 0);
 		return result;
 	}
+	/**
+	* Read back a single config path and compare it to the value we tried to
+	* write. Used by `applyConfig`'s verify-after-write: a `config set` can exit
+	* non-zero (a hot-reload races the write, OpenClaw's clobber protection
+	* fires) even though the value actually landed, exactly like `applyPlugin`'s
+	* install-then-check tolerance.
+	*
+	* OpenClaw REDACTS sensitive values on `config get`, returning the literal
+	* `__OPENCLAW_REDACTED__` instead of the real value. Treat that as a match:
+	* the key exists and OpenClaw is hiding it, so a deep-equal against the
+	* intended value would otherwise be a false negative and force a re-throw.
+	*/
+	async configValueMatches(path, expected) {
+		try {
+			const { stdout } = await execFileAsync$1("openclaw", [
+				"config",
+				"get",
+				path
+			], { timeout: 1e4 });
+			const actual = JSON.parse(stdout.trim());
+			if (actual === OPENCLAW_REDACTED) return true;
+			return deepEqual(actual, expected);
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Run a read-back `check` with the same retry/backoff cadence as the config
+	* writes — the settling hot-reload may still be rewriting openclaw.json when
+	* we first read back, so a single check can be a false negative. Returns true
+	* on the first success, false once all attempts are exhausted.
+	*/
+	async verifyApplied(check) {
+		for (let attempt = 0; attempt <= this.configSetRetries; attempt++) {
+			if (await check()) return true;
+			if (attempt < this.configSetRetries && this.configSetRetryDelayMs > 0) await delay$1(this.configSetRetryDelayMs * 2 ** attempt);
+		}
+		return false;
+	}
 	async applyPlugin(spec, _installPath, opts) {
 		const pkg = stripPluginVersion(spec);
 		await this.ensurePluginsAllow(pkg);
@@ -2023,6 +2092,13 @@ var OpenClawApplier = class {
 			try {
 				await this.runConfigSet([parentPath, JSON.stringify(merged)]);
 			} catch (err) {
+				if (await this.verifyApplied(async () => {
+					const after = await readParentObject(parentPath);
+					return [...dottedKvs.entries()].every(([k, v]) => deepEqual(after[k], v));
+				})) {
+					log$3.warn({ parentPath }, "openclaw config set exited non-zero but config landed — continuing");
+					continue;
+				}
 				log$3.error({
 					err: err instanceof Error ? err.message : String(err),
 					parentPath
@@ -2033,11 +2109,16 @@ var OpenClawApplier = class {
 		if (leaves.length > 0) try {
 			await this.runConfigSet(["--batch-json", JSON.stringify(leaves)]);
 		} catch (err) {
-			log$3.error({
-				err: err instanceof Error ? err.message : String(err),
-				batch: leaves
-			}, "Failed to set config via openclaw config set --batch-json");
-			throw err;
+			if (await this.verifyApplied(async () => {
+				return (await Promise.all(leaves.map((l) => this.configValueMatches(l.path, l.value)))).every(Boolean);
+			})) log$3.warn({ count: leaves.length }, "openclaw config set --batch-json exited non-zero but config landed — continuing");
+			else {
+				log$3.error({
+					err: err instanceof Error ? err.message : String(err),
+					batch: leaves
+				}, "Failed to set config via openclaw config set --batch-json");
+				throw err;
+			}
 		}
 	}
 	/**
@@ -2112,11 +2193,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
@@ -2162,9 +2249,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();
@@ -2189,13 +2276,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;
 	}
@@ -2230,8 +2320,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();
@@ -2239,13 +2330,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);
@@ -2329,23 +2420,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`.
 	*/
-	unsetConfigKey(key) {
-		return this.runConfigCommand(["unset", key]);
+	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;
 	}
 	/**
-	* 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.
+	* 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.
+	*/
+	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>` (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 () => {
@@ -2421,15 +2529,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.0",
+  "version": "0.2.2",
   "description": "Integration lifecycle management for Alfe — registry, resolution, installation, and state",
   "type": "module",
   "main": "./dist/index.js",