@alfe.ai/integrations 0.1.5 → 0.2.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { IntegrationManifest, IntegrationStateEntry, IntegrationStatus, IntegrationsStateFile, McpServerDeclaration, PluginInstall, SkillInstall } from "@alfe.ai/integration-manifest";
-import { Manager } from "@alfe.ai/mcp-bundler";
+import { Manager, StoredServerEntry } from "@alfe.ai/mcp-bundler";
 
 //#region src/registry.d.ts
 
@@ -287,6 +287,13 @@ interface RuntimeApplier {
   applyPlugin(pkg: string, integrationInstallPath: string, opts?: {
     force?: boolean;
   }): Promise<void>;
+  /**
+   * Optional: pre-trust an integration's full plugin set in one write before
+   * the per-plugin install loop. Runtimes whose config writes trigger a reload
+   * (OpenClaw) implement this to collapse N allowlist writes into one. Absent
+   * → the manager relies on `applyPlugin` to allowlist each plugin itself.
+   */
+  ensurePluginsAllowed?(pkgs: string[]): Promise<void>;
   /** Remove a plugin package from this runtime */
   removePlugin(pkg: string): Promise<void>;
   /** Copy a skill directory into this runtime's skills location */
@@ -301,6 +308,18 @@ interface RuntimeApplier {
   applyConfig(integrationId: string, config: Record<string, unknown>): Promise<void>;
   /** Remove config previously applied by an integration */
   removeConfig(integrationId: string): Promise<void>;
+  /**
+   * Optional: write a single raw config key/value directly to the runtime,
+   * bypassing the per-integration removal accounting that `applyConfig`
+   * maintains. Used by the daemon's `alfe.config_set` cloud-command so it can
+   * route per-runtime instead of shelling the runtime CLI directly.
+   *
+   * MUST NOT funnel through `applyConfig` — a raw single-key set is untracked
+   * and must not corrupt an integration's tracked config contribution.
+   * Appliers that can't honour a raw write omit this method; callers detect
+   * its absence and degrade gracefully.
+   */
+  setConfigRaw?(key: string, value: string): Promise<void>;
   /** Check if this runtime is available (e.g. workspace directory exists) */
   isAvailable(): Promise<boolean>;
 }
@@ -748,6 +767,10 @@ interface OpenClawApplierOptions {
   skillsDir?: string;
   /** Path to the integration tracking file (defaults to {home}/config.json) */
   configPath?: string;
+  /** Max retries for a transient `openclaw config set` failure (default 3) */
+  configSetRetries?: number;
+  /** Backoff between `openclaw config set` retries, ms (default 750; set 0 in tests) */
+  configSetRetryDelayMs?: number;
 }
 declare class OpenClawApplier implements RuntimeApplier {
   readonly runtime = "openclaw";
@@ -755,15 +778,44 @@ declare class OpenClawApplier implements RuntimeApplier {
   private agentWorkspace;
   private skillsDir;
   private trackingPath;
+  private configSetRetries;
+  private configSetRetryDelayMs;
+  /** Serializes all `openclaw config set` writes so they never interleave with each other or the hot-reload they trigger. */
+  private configSetQueue;
   constructor(options: OpenClawApplierOptions);
+  /** Convenience: `openclaw config set <args>`, serialized + retried. */
+  private runConfigSet;
+  /**
+   * Run `openclaw config <args>` (set/unset), serialized against every other
+   * config write and retried with backoff. See CONFIG_SET_RETRIES for why:
+   * each write triggers a runtime hot-reload that rewrites openclaw.json, and a
+   * follow-up command that races the reload fails with a bare "Command failed".
+   *
+   * 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 payload.
+   */
+  private runConfigCommand;
   applyPlugin(spec: string, _installPath?: string, opts?: {
     force?: boolean;
   }): Promise<void>;
   /**
-   * Ensure the plugin is in plugins.allow in openclaw.json.
+   * Ensure one or more plugins are in plugins.allow in openclaw.json.
    * Uses `openclaw config set` to avoid clobbering OpenClaw's own file format.
+   *
+   * Prefer passing the FULL set of plugins for an integration in a single call
+   * (see `ensurePluginsAllowed`): each write triggers a runtime hot-reload, so
+   * one write for N plugins is one reload instead of N.
    */
   private ensurePluginsAllow;
+  /**
+   * Pre-trust every plugin an integration ships in a SINGLE plugins.allow
+   * write, before any are installed. Called once by the manager ahead of the
+   * per-plugin install loop so activation triggers one hot-reload for the
+   * allowlist instead of one per plugin. `applyPlugin`'s own per-plugin
+   * `ensurePluginsAllow` then finds nothing missing and is a no-op.
+   */
+  ensurePluginsAllowed(specs: string[]): Promise<void>;
   /**
    * Check if a plugin is already installed.
    *
@@ -802,11 +854,238 @@ declare class OpenClawApplier implements RuntimeApplier {
    * then removes them via `openclaw config unset`.
    */
   removeConfig(integrationId: string): Promise<void>;
+  /**
+   * Raw single-key config write — `openclaw config set <key> <value>`.
+   *
+   * Deliberately bypasses the `_integrations` tracking that `applyConfig`
+   * maintains: this is a fire-and-forget write for the `alfe.config_set`
+   * cloud-command, not an integration contribution, so it must NOT be
+   * recorded for later `removeConfig` teardown. Reuses the serialized +
+   * retried queue so it can't interleave with the hot-reload that integration
+   * config writes trigger.
+   */
+  setConfigRaw(key: string, value: string): Promise<void>;
+  isAvailable(): Promise<boolean>;
+  private readTracking;
+  private writeTracking;
+}
+//#endregion
+//#region src/appliers/hermes-applier.d.ts
+interface HermesApplierOptions {
+  /**
+   * Path to the Hermes home directory (e.g. ~/.hermes) — where config.yaml,
+   * .env, and plugins/ live. For Hermes, home == workspace.
+   */
+  home?: string;
+  /**
+   * @deprecated Use `home`. Kept for parity with OpenClawApplier's option shape —
+   * when set, used as `home`.
+   */
+  workspace?: string;
+  /** Path to the per-integration tracking file (defaults to {home}/.alfe-integrations.json) */
+  configPath?: string;
+  /** Max retries for a transient `hermes config set/unset` failure (default 3) */
+  configSetRetries?: number;
+  /** Backoff between `hermes config` retries, ms (default 750; set 0 in tests) */
+  configSetRetryDelayMs?: number;
+}
+declare class HermesApplier implements RuntimeApplier {
+  readonly runtime = "hermes";
+  private home;
+  private trackingPath;
+  private configSetRetries;
+  private configSetRetryDelayMs;
+  /** Serializes all `hermes config` writes so they never interleave. */
+  private configSetQueue;
+  constructor(options?: HermesApplierOptions);
+  /**
+   * Apply integration config to the Hermes runtime via `hermes config set`.
+   *
+   * Each leaf is applied as `hermes config set <dotted.key> <value>`. Each
+   * integration's config contribution is tracked in the tracking file so it can
+   * be cleanly removed later (mirrors OpenClawApplier's `_integrations`).
+   */
+  applyConfig(integrationId: string, config: Record<string, unknown>): Promise<void>;
+  /**
+   * 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.
+   */
+  removeConfig(integrationId: string): Promise<void>;
+  /**
+   * Raw single-key config write — `hermes config set <key> <value>`.
+   *
+   * Deliberately bypasses the `_integrations` tracking that `applyConfig`
+   * maintains: this is a fire-and-forget write for the `alfe.config_set`
+   * cloud-command, NOT an integration contribution, so it must not be recorded
+   * for later `removeConfig` teardown (doing so would corrupt the
+   * per-integration removal accounting). Reuses the serialized queue.
+   */
+  setConfigRaw(key: string, value: string): Promise<void>;
+  /**
+   * Apply a plugin. The `@alfe.ai/openclaw-*` npm plugins are OpenClaw-specific
+   * (they carry the `openclaw` peer dep) and do NOT apply to Hermes — log + skip
+   * them. The manager catches per-plugin, so a skip here is a correct no-op.
+   *
+   * A genuine Hermes-native plugin spec (git URL / pip / local dir) would
+   * `hermes plugins install` then `hermes plugins enable`; no manifest declares
+   * one in Phase 1, so this path is a real attempt (not faked) but untrodden.
+   */
+  applyPlugin(spec: string): Promise<void>;
+  /**
+   * Remove a plugin. OpenClaw-specific npm plugins were never installed into
+   * Hermes (applyPlugin skipped them), so removal is a no-op log. A native
+   * Hermes plugin would be disabled via `hermes plugins`.
+   */
+  removePlugin(spec: string): Promise<void>;
+  applySkill(name: string): Promise<void>;
+  removeSkill(name: string): Promise<void>;
+  applyClawHubSkill(slug: string): Promise<void>;
+  removeClawHubSkill(slug: string): Promise<void>;
   isAvailable(): Promise<boolean>;
+  /** 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.
+   */
+  private runConfigCommand;
   private readTracking;
   private writeTracking;
 }
 //#endregion
+//#region src/appliers/hermes-mcp-sync.d.ts
+/**
+ * The slice of the bundler `Manager` this consumer needs. Kept structural (not a
+ * concrete-class dependency) so it stays trivially testable and so the consumer
+ * can never reach for producer-side mutation methods — it is read-only over the
+ * store plus a change subscription.
+ */
+interface McpStoreReader {
+  onChange(cb: () => void): () => void;
+  listServers(): {
+    id: string;
+    entry: StoredServerEntry;
+  }[];
+}
+interface HermesMcpSyncOptions {
+  /** The runtime-agnostic MCP store manager (read + onChange). */
+  manager: McpStoreReader;
+  /** Hermes home (== workspace == ~/.hermes). config.yaml + .env live here. */
+  home?: string;
+  /**
+   * The `ALFE_API_KEY` value to write into `~/.hermes/.env` so the
+   * `${ALFE_API_KEY}` refs in mirrored server envs resolve. In managed mode this
+   * is the daemon's own api key; self-hosted threads it explicitly. When absent,
+   * the `.env` write is skipped and a warning is logged (the servers would then
+   * start in zero-accounts degraded mode).
+   */
+  apiKey?: string;
+  /**
+   * Trigger a runtime reload after a real change. MUST be the SAME callback the
+   * daemon wires into `setRuntimeRestartNeededHandler` — there is exactly one
+   * restart path. No-op when the runtime isn't running yet (the initial sync
+   * writes config.yaml before Hermes starts, so no restart is needed then).
+   */
+  requestRestart?: () => void;
+  /** Override config.yaml path (defaults to {home}/config.yaml). For tests. */
+  configPath?: string;
+  /** Override .env path (defaults to {home}/.env). For tests. */
+  envPath?: string;
+  /**
+   * Override the sidecar that records which `mcp_servers` ids this sync wrote
+   * (defaults to {home}/.alfe-mcp-synced.json). Used so removals survive daemon
+   * restarts and so we NEVER delete user-authored `mcp_servers` entries.
+   */
+  trackingPath?: string;
+  /**
+   * Trailing debounce (ms) used to coalesce a burst of store mutations (one
+   * integration install fires `addServer` once per server) into a single
+   * config.yaml write + restart, avoiding a restart storm. Default 250; set 0 in
+   * tests. The initial sync in `start()` is always immediate.
+   */
+  debounceMs?: number;
+}
+/**
+ * Read-merge-write mirror of the MCP store into `~/.hermes/config.yaml`.
+ *
+ * Ownership / removal model: every entry returned by `manager.listServers()`
+ * comes from the Alfe store (its `owner` is `integration:<id>` / `cli` /
+ * `manual`) and is therefore Alfe-owned — these are the ids we write. User
+ * authored `mcp_servers` entries live ONLY in config.yaml and never appear in
+ * the store, so we never touch them. To know which config.yaml ids to REMOVE
+ * when a server leaves the store, we persist the set of ids we last wrote to a
+ * sidecar (`.alfe-mcp-synced.json`) and only ever delete from that set — exactly
+ * how the bundler store tracks `_ownedOpenclawKeys` for its openclaw.json mirror.
+ */
+declare class HermesMcpSync {
+  private readonly manager;
+  private readonly home;
+  private readonly apiKey?;
+  private readonly requestRestart?;
+  private readonly configPath;
+  private readonly envPath;
+  private readonly trackingPath;
+  private readonly debounceMs;
+  /** Ids of `mcp_servers` entries this sync last wrote — the removal set. */
+  private syncedIds;
+  /** Serializes syncs so two onChange-driven runs can't interleave file writes. */
+  private queue;
+  private unsubscribe?;
+  private debounceTimer?;
+  private started;
+  constructor(opts: HermesMcpSyncOptions);
+  /**
+   * Begin mirroring: load the prior removal set, run one immediate sync (so
+   * config.yaml reflects the current store before Hermes first starts), then
+   * subscribe to store changes (debounced). Idempotent.
+   */
+  start(): void;
+  /** Stop subscribing and cancel any pending debounced sync. Idempotent. */
+  stop(): void;
+  /**
+   * Mirror the current store into config.yaml + .env exactly once. Public so the
+   * daemon (and tests) can await a deterministic sync. Serialized against any
+   * other in-flight sync.
+   */
+  syncOnce(): Promise<void>;
+  private schedule;
+  private syncNow;
+  private computeDesired;
+  /**
+   * Transform a stored entry into a Hermes `mcp_servers` entry. SPIKE-PENDING
+   * SEAM #3 lives here — the schema shape. stdio entries get `ALFE_API_KEY`
+   * injected; remote entries pass through (Hermes supports `url`-based MCP).
+   */
+  private toHermesEntry;
+  private withAlfeApiKey;
+  /** Read-merge-write `~/.hermes/.env` to set ALFE_API_KEY without clobbering other keys. */
+  private ensureEnvApiKey;
+  private loadSyncedIds;
+  private persistSyncedIds;
+}
+/**
+ * Set `KEY=value` in a `.env`-style file, preserving every other line (comments,
+ * blank lines, unrelated keys) and order. Returns whether the file changed. Not
+ * a full dotenv parser — it only matches simple `KEY=` lines, which is all
+ * `~/.hermes/.env` ever holds.
+ */
+declare function upsertEnvVar(envPath: string, key: string, value: string): boolean;
+//#endregion
 //#region src/lock.d.ts
 interface RuntimePluginEntry {
   /**
@@ -826,9 +1105,29 @@ interface RuntimeSkillEntry {
   sourceIntegration: string;
   integrationVersion: string;
 }
+/**
+ * Records that an integration applied runtime *config* (via the applier's
+ * `applyConfig`) to a runtime — even when it contributed no plugins/skills.
+ *
+ * Without this, a config-only integration left no lock entry for its runtime,
+ * so `removeEntries` returned nothing for it and `deactivate` never drove
+ * `applier.removeConfig(...)` — leaking the applied config on removal. The
+ * applier itself owns the actual config payload (e.g. OpenClaw's tracking
+ * file); the lock only needs to know which integration touched which runtime.
+ */
+interface RuntimeConfigEntry {
+  sourceIntegration: string;
+  integrationVersion: string;
+}
 interface RuntimeDesiredState {
   plugins: RuntimePluginEntry[];
   skills: RuntimeSkillEntry[];
+  /**
+   * Integrations that applied config to this runtime. Optional for
+   * back-compat with lock files written before this field existed — always
+   * read it as `state.config ?? []`.
+   */
+  config?: RuntimeConfigEntry[];
 }
 interface RuntimeLockFile {
   version: 1;
@@ -848,15 +1147,26 @@ declare class LockManager {
   write(lock: RuntimeLockFile): void;
   /**
    * Add entries for an integration activation in a specific runtime.
+   *
+   * Pass `opts.configApplied` when the integration applied runtime config so
+   * the contribution is recorded even if it ships no plugins/skills — this is
+   * what lets a config-only integration be torn down on deactivate.
    */
-  addEntries(runtime: string, integrationId: string, version: string, plugins: PluginInstall[], skills: SkillInstall[], installPath: string): void;
+  addEntries(runtime: string, integrationId: string, version: string, plugins: PluginInstall[], skills: SkillInstall[], installPath: string, opts?: {
+    configApplied?: boolean;
+  }): void;
   /**
    * Remove all entries for a given integration across all runtimes.
    * Returns what was removed, keyed by runtime.
+   *
+   * A runtime is included in the result when the integration contributed
+   * plugins, skills, OR config there — so `deactivate` drives
+   * `applier.removeConfig` even for a config-only integration.
    */
   removeEntries(integrationId: string): Record<string, {
     plugins: RuntimePluginEntry[];
     skills: RuntimeSkillEntry[];
+    config: RuntimeConfigEntry[];
   }>;
   /**
    * Get the full desired state for a specific runtime.
@@ -924,4 +1234,4 @@ declare class IntegrationManagerAdapter implements IIntegrationManager {
   resetReinstallAttempts(integrationId: string): void;
 }
 //#endregion
-export { type CredentialsResolver, DEFAULT_REGISTRY_TTL_MS, type HookEnvOptions, type HookResult, type IIntegrationManager, type InstalledInfo, Installer, InstallerError, type IntegrationConfigureParams, type IntegrationHealthParams, type IntegrationInfo, type IntegrationInstallParams, IntegrationManager, IntegrationManagerAdapter, type IntegrationManagerOptions, type IntegrationRemoveParams, type LoadOptions, LockManager, McpApplier, type McpApplierOptions, OpenClawApplier, type OpenClawApplierOptions, type PlatformContext, Registry, type RegistryEntry, type RegistryFetcher, type RegistryIndex, type RegistryOptions, RegistryResolveError, type ResolveOptions, type ResolvedIntegration, Resolver, type RuntimeApplier, type RuntimeDesiredState, type RuntimeLockFile, type RuntimePluginEntry, type RuntimeSkillEntry, StateManager, buildHookEnv, resolveInstallsForRuntime, runHook, runHookWithContext };
+export { type CredentialsResolver, DEFAULT_REGISTRY_TTL_MS, HermesApplier, type HermesApplierOptions, HermesMcpSync, type HermesMcpSyncOptions, type HookEnvOptions, type HookResult, type IIntegrationManager, type InstalledInfo, Installer, InstallerError, type IntegrationConfigureParams, type IntegrationHealthParams, type IntegrationInfo, type IntegrationInstallParams, IntegrationManager, IntegrationManagerAdapter, type IntegrationManagerOptions, type IntegrationRemoveParams, type LoadOptions, LockManager, McpApplier, type McpApplierOptions, type McpStoreReader, OpenClawApplier, type OpenClawApplierOptions, type PlatformContext, Registry, type RegistryEntry, type RegistryFetcher, type RegistryIndex, type RegistryOptions, RegistryResolveError, type ResolveOptions, type ResolvedIntegration, Resolver, type RuntimeApplier, type RuntimeConfigEntry, type RuntimeDesiredState, type RuntimeLockFile, type RuntimePluginEntry, type RuntimeSkillEntry, StateManager, buildHookEnv, resolveInstallsForRuntime, runHook, runHookWithContext, upsertEnvVar };