@alfe.ai/integrations 0.5.4 → 0.6.1

package/README.md

@@ -45,7 +45,8 @@ import {
 } from '@alfe.ai/integrations';
 
 // ── Registry + Resolution ──────────────────────────────────
-const registry = new Registry();
+const registryFetcher = () => apiClient.integrations.getRegistry();
+const registry = new Registry(registryFetcher);
 const results = await registry.search('discord');
 
 const resolver = new Resolver(registry);
@@ -56,8 +57,9 @@ const installPath = await installer.install(resolved);
 
 // ── Lifecycle Management ───────────────────────────────────
 const manager = new IntegrationManager({
-  logger,
-  skillsDir: '~/.alfe/skills/',  // default
+  registryFetcher,
+  runtimeAppliers: new Map([['openclaw', openClawApplier]]),
+  mcpApplier,
 });
 
 await manager.install({ name: 'discord', version: '1.0.0' });
@@ -73,20 +75,20 @@ cloudClient.setIntegrationManager(adapter);
 
 ## Configuration
 
-The `Registry` class resolves the API URL in this order:
-
-1. Explicit `apiUrl` constructor argument
-2. `ALFE_API_URL` environment variable
-3. `https://api.alfe.ai` (production default)
+`Registry` is transport-independent. Callers provide a `RegistryFetcher`,
+normally backed by `@alfe.ai/api-client`; the package does not read an API URL
+or perform HTTP directly.
 
 The `IntegrationManager` accepts an options object:
 
 ```typescript
 interface IntegrationManagerOptions {
-  logger?: Logger;
-  statePath?: string;       // default: ~/.alfe/integrations.json
+  registryFetcher: RegistryFetcher;
+  statePath?: string;        // default: ~/.alfe/integrations.json
   integrationsDir?: string;  // default: ~/.alfe/integrations/
-  skillsDir?: string;        // default: ~/.alfe/skills/
+  lockPath?: string;         // default: ~/.alfe/runtime-lock.json
+  runtimeAppliers?: Map<string, RuntimeApplier>;
+  mcpApplier?: McpApplier;   // required when manifests declare mcp_servers
 }
 ```
 

package/dist/index.d.ts

@@ -95,6 +95,7 @@ interface LoadOptions {
 declare class Registry {
   private index;
   private loadedAt;
+  private loadPromise;
   private fetcher;
   private ttlMs;
   /**
@@ -249,12 +250,14 @@ declare class Installer {
    */
   stage(resolved: ResolvedIntegration): Promise<string>;
   /**
-   * Commit a previously-staged clone: remove the live install dir and rename
-   * the staged dir into its place. Same-filesystem `renameSync` makes the swap
-   * near-atomic (no window where the install dir is half-populated). Called
-   * inside the runtime-suspension window during a diff-based upgrade.
+   * Commit a previously-staged clone with a recoverable same-filesystem swap.
+   * The live dir first moves to a deterministic backup, then the staged dir
+   * moves into place. A failed second rename restores the prior install; a
+   * daemon crash is recovered on the next `getInstallPath()` call.
    */
   commitStaged(name: string, stagedPath: string): void;
+  /** Restore a live install left in the deterministic backup by a killed swap. */
+  private recoverInterruptedSwap;
   /**
    * Remove any orphaned `.staging-*` directories under the base path. Called at
    * the start of `stage()` so a daemon killed mid-upgrade doesn't accumulate
@@ -290,6 +293,21 @@ declare class Installer {
    */
   private installLocalDependencies;
   private runNpmInstall;
+  /**
+   * Pre-fetch every npx-executed MCP server package the manifest declares
+   * (e.g. `command: npx, args: ["-y", "@alfe.ai/xero-mcp@0.3.8"]`) into the
+   * npx cache, WITHOUT executing the server. The first bundler connect then
+   * spawns from a warm cache instead of paying a 30-90s npm download during
+   * the MCP handshake — where it used to blow the connect budget and strand
+   * the server's tools until a daemon restart.
+   *
+   * Strictly best-effort: a missing/unparseable manifest, a non-npx command,
+   * or a failed download logs a warning and moves on — an install must never
+   * fail because a pre-warm did.
+   */
+  prewarmMcpNpxPackages(installPath: string): Promise<void>;
+  /** Populate the npx cache for a package spec via a no-op command. */
+  private runNpx;
   /**
    * List all locally installed integrations.
    */
@@ -298,6 +316,7 @@ declare class Installer {
    * Check if an integration is installed.
    */
   isInstalled(name: string): boolean;
+  private validateResolved;
 }
 //#endregion
 //#region src/runtime-applier.d.ts
@@ -510,6 +529,7 @@ interface IntegrationManagerOptions {
   logger?: unknown;
   statePath?: string;
   integrationsDir?: string;
+  /** @deprecated Skills directories are owned by each RuntimeApplier. */
   skillsDir?: string;
   /** Runtime appliers keyed by runtime name */
   runtimeAppliers?: Map<string, RuntimeApplier>;
@@ -521,7 +541,8 @@ interface IntegrationManagerOptions {
    * Runtime-agnostic MCP server applier. The manager routes
    * `mcp_servers` declarations through it once per integration (the
    * applier writes to the bundler store + openclaw.json mirror).
-   * Required — there is no fallback path; integrations with
+   * Operationally required when manifests declare MCP servers. There is no
+   * fallback path; integrations with
    * `mcp_servers` will skip MCP registration silently if this is
    * omitted (the warn log makes this visible).
    */
@@ -716,8 +737,10 @@ declare class IntegrationManager {
   /**
    * Build a hook-failure message. A hook we SIGKILLed at its timeout is rendered
    * as `(timed out after <ms>ms)` so it is visually distinguishable in Sentry
-   * from a genuine non-zero exit `(exit <code>)` — the two have very different
-   * root causes (Sentry AGENT-DAEMON-6).
+   * from a genuine non-zero exit `(exit <code>)`. Captured output is deliberately
+   * excluded: hooks inherit daemon credentials and receive integration secrets,
+   * so stdout/stderr is a secret-bearing channel that must not enter durable
+   * state, logs, or user-facing error messages.
    */
   private hookFailureMessage;
   /**
@@ -739,9 +762,9 @@ declare class IntegrationManager {
    * (and everything a sibling integration still claims) in place. Phase 4's
    * `activate` re-applies and re-locks the new set immediately after.
    *
-   * `removeEntries` clears this integration's lock rows and returns what it had;
-   * a candidate removal is skipped when it is EITHER (a) still declared by the
-   * new manifest, or (b) still claimed by another integration.
+   * The existing lock remains intact until every physical removal and MCP prune
+   * succeeds. This makes partial cleanup retryable; only then are the old rows
+   * cleared so activate() can record the new manifest's contributions.
    */
   private applyUpgradeDiffRemovals;
   /**
@@ -758,7 +781,6 @@ declare class IntegrationManager {
 //#region src/state.d.ts
 declare class StateManager {
   private filePath;
-  private lockHeld;
   constructor(filePath?: string);
   /**
    * Read the current state file. Returns empty state if file doesn't exist.
@@ -1215,8 +1237,9 @@ declare class OpenClawApplier implements RuntimeApplier {
    * Drop a set of dotted keys from a dot-free parent object via read-drop-write,
    * UNLOCKED. If the parent becomes empty, `config unset` it; otherwise
    * `--replace` the shrunk map (siblings survive because they remain in
-   * `remaining`). Warn-tolerant — a failed drop of an already-gone key must not
-   * fail the caller. Shared by `removeConfig` (whole-integration teardown) and
+   * `remaining`). A proven already-absent path is idempotent success; every
+   * other write failure propagates so callers retain the ownership record for a
+   * later retry. Shared by `removeConfig` (whole-integration teardown) and
    * `applyConfig`'s stale-key diff (per-key removal between manifest versions).
    *
    * Assumes the shared CLI lock is already held by the calling public method —
@@ -1240,10 +1263,11 @@ declare class OpenClawApplier implements RuntimeApplier {
    * the provider subtree is unset for `models.providers.zhipu.baseUrl`, the
    * follow-up `.apiKey` / `.models` leaves skip re-issuing the parent unset.
    *
-   * Warn-tolerant (a failed unset of an already-gone key must never fail the
-   * caller) and assumes the shared CLI lock is held — stays an `*Unlocked`
-   * internal since the lock is NOT re-entrant. Shared by `removeConfig`
-   * (whole-integration teardown) and `applyConfig`'s stale-leaf diff.
+   * A proven already-absent path is idempotent success; every other failure
+   * propagates so the ownership ledger remains a retry record. Assumes the
+   * shared CLI lock is held — stays an `*Unlocked` internal since the lock is
+   * NOT re-entrant. Shared by `removeConfig` (whole-integration teardown) and
+   * `applyConfig`'s stale-leaf diff.
    */
   private unsetLeafPathUnlocked;
   /**
@@ -1753,6 +1777,11 @@ interface RuntimeLockFile {
   runtimes: Record<string, RuntimeDesiredState>;
   updatedAt: string;
 }
+interface IntegrationRuntimeEntries {
+  plugins: RuntimePluginEntry[];
+  skills: RuntimeSkillEntry[];
+  config: RuntimeConfigEntry[];
+}
 declare class LockManager {
   private filePath;
   constructor(filePath?: string);
@@ -1774,6 +1803,12 @@ declare class LockManager {
   addEntries(runtime: string, integrationId: string, version: string, plugins: PluginInstall[], skills: SkillInstall[], installPath: string, opts?: {
     configApplied?: boolean;
   }): void;
+  /**
+   * Snapshot an integration's entries without changing the lock. Teardown uses
+   * this first and only clears the entries after every physical removal
+   * succeeds, making a failed cleanup retryable.
+   */
+  getEntriesForIntegration(integrationId: string): Record<string, IntegrationRuntimeEntries>;
   /**
    * Remove all entries for a given integration across all runtimes.
    * Returns what was removed, keyed by runtime.
@@ -1782,11 +1817,7 @@ declare class LockManager {
    * 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[];
-  }>;
+  removeEntries(integrationId: string): Record<string, IntegrationRuntimeEntries>;
   /**
    * Get the full desired state for a specific runtime.
    */
@@ -1874,4 +1905,4 @@ declare class IntegrationManagerAdapter implements IIntegrationManager {
   resetReinstallAttempts(integrationId: string): void;
 }
 //#endregion
-export { ClaudeCodeApplier, type ClaudeCodeApplierOptions, ClaudeCodeMcpSync, type ClaudeCodeMcpSyncOptions, 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, NoopOpenClawCliLock, OpenClawApplier, type OpenClawApplierOptions, type OpenClawCliLock, 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, SerialOpenClawCliLock, StateManager, buildHookEnv, resolveInstallsForRuntime, runHook, runHookWithContext, upsertEnvVar };
+export { ClaudeCodeApplier, type ClaudeCodeApplierOptions, ClaudeCodeMcpSync, type ClaudeCodeMcpSyncOptions, 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 IntegrationRuntimeEntries, type LoadOptions, LockManager, McpApplier, type McpApplierOptions, type McpStoreReader, NoopOpenClawCliLock, OpenClawApplier, type OpenClawApplierOptions, type OpenClawCliLock, 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, SerialOpenClawCliLock, StateManager, buildHookEnv, resolveInstallsForRuntime, runHook, runHookWithContext, upsertEnvVar };