@alfe.ai/integrations 0.1.4 → 0.1.5

package/dist/index.d.ts

@@ -8,6 +8,14 @@ import { Manager } from "@alfe.ai/mcp-bundler";
  *
  * Calls GET /integrations/registry (public, no auth required) and caches the result.
  * The API URL can be passed explicitly or set via ALFE_API_URL env var.
+ *
+ * The cache is time-bounded by a TTL (default 60s). Long-running consumers — chiefly
+ * the agent daemon, which constructs the Registry once at startup and never restarts —
+ * would otherwise be pinned to the registry snapshot taken at process boot, and could
+ * never resolve a version published after the daemon came up (the "stale cache" bug).
+ * With a TTL, every consumer self-heals within a bounded window. The resolve-for-install
+ * path additionally forces a fresh read (see `load({ fresh: true })`) because installing
+ * a specific version is a rare, correctness-critical action that must never race the TTL.
  */
 interface RegistryEntry {
   /** Human-readable display name (e.g. 'Alfe Voice') */
@@ -69,26 +77,51 @@ interface RegistryIndex {
 type RegistryFetcher = () => Promise<(RegistryEntry & {
   id: string;
 })[]>;
+/** Default cache TTL — refetch the registry index after this many ms. */
+declare const DEFAULT_REGISTRY_TTL_MS = 60000;
+interface RegistryOptions {
+  /**
+   * How long (ms) a loaded index is considered fresh before `load()` refetches.
+   * Defaults to {@link DEFAULT_REGISTRY_TTL_MS} (60s). A non-positive value
+   * disables time-based caching (every `load()` refetches).
+   */
+  ttlMs?: number;
+}
+/** Options for a single `load()` call. */
+interface LoadOptions {
+  /** Bypass the cache and refetch the index even if it's still within TTL. */
+  fresh?: boolean;
+}
 declare class Registry {
   private index;
+  private loadedAt;
   private fetcher;
+  private ttlMs;
   /**
    * @param fetcher - Function that fetches the integrations array from the registry API.
    *                  Typically backed by api-client's IntegrationsService.getRegistry().
+   * @param options - Optional cache configuration (TTL).
    */
-  constructor(fetcher: RegistryFetcher);
+  constructor(fetcher: RegistryFetcher, options?: RegistryOptions);
+  /** True when the cached index is absent or older than the TTL. */
+  private isStale;
   /**
-   * Load the registry index. Uses cache if already loaded.
+   * Load the registry index. Returns the cached index while it's still within
+   * TTL; refetches once the cache is stale (or when `{ fresh: true }` is passed).
    */
-  load(): Promise<RegistryIndex>;
+  load(options?: LoadOptions): Promise<RegistryIndex>;
   /**
-   * Force reload the index (bypass cache).
+   * Force reload the index (bypass cache). Equivalent to `load({ fresh: true })`.
    */
   reload(): Promise<RegistryIndex>;
   /**
    * Get a specific integration entry by name.
+   *
+   * @param fresh - When true, force a fresh fetch before reading (used by the
+   *                resolve-for-install path so a stale version list never blocks
+   *                a just-published version).
    */
-  get(id: string): Promise<RegistryEntry | undefined>;
+  get(id: string, fresh?: boolean): Promise<RegistryEntry | undefined>;
   /**
    * List all integrations in the registry.
    */
@@ -115,6 +148,20 @@ interface ResolvedIntegration {
   subdir?: string;
   description: string;
 }
+/** Options for a single `resolve()` call. */
+interface ResolveOptions {
+  /**
+   * Bypass the registry cache and read a fresh index before resolving.
+   *
+   * The install/reconcile path sets this: installing a specific version is a
+   * rare, user-triggered, correctness-critical action that must never resolve
+   * against a stale cached version list (the cause of the
+   * `Version "x" not found … Available versions: …` install failure on a
+   * long-running daemon). High-frequency read-only uses (marketplace
+   * listing/search) leave it unset and keep the TTL cache.
+   */
+  fresh?: boolean;
+}
 declare class RegistryResolveError extends Error {
   constructor(message: string);
 }
@@ -126,9 +173,11 @@ declare class Resolver {
    *
    * @param name - Integration name (e.g. "discord")
    * @param version - Specific version (e.g. "1.0.0") or undefined for latest
+   * @param options - Pass `{ fresh: true }` to bypass the registry cache
+   *                  (used by the install/reconcile path).
    * @returns Resolved integration with repo URL and commit hash
    */
-  resolve(id: string, version?: string): Promise<ResolvedIntegration>;
+  resolve(id: string, version?: string, options?: ResolveOptions): Promise<ResolvedIntegration>;
   /**
    * Check if an integration exists in the registry.
    */
@@ -875,4 +924,4 @@ declare class IntegrationManagerAdapter implements IIntegrationManager {
   resetReinstallAttempts(integrationId: string): void;
 }
 //#endregion
-export { type CredentialsResolver, type HookEnvOptions, type HookResult, type IIntegrationManager, type InstalledInfo, Installer, InstallerError, type IntegrationConfigureParams, type IntegrationHealthParams, type IntegrationInfo, type IntegrationInstallParams, IntegrationManager, IntegrationManagerAdapter, type IntegrationManagerOptions, type IntegrationRemoveParams, LockManager, McpApplier, type McpApplierOptions, OpenClawApplier, type OpenClawApplierOptions, type PlatformContext, Registry, type RegistryEntry, type RegistryFetcher, type RegistryIndex, RegistryResolveError, 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, 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 };

package/dist/index.js

@@ -6,21 +6,34 @@ import { closeSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, op
 import { buildConfigValidationSchema, parseManifestFile } from "@alfe.ai/integration-manifest";
 import { createLogger } from "@auriclabs/logger";
 //#region src/registry.ts
+/** Default cache TTL — refetch the registry index after this many ms. */
+const DEFAULT_REGISTRY_TTL_MS = 6e4;
 var Registry = class {
 	index = null;
+	loadedAt = 0;
 	fetcher;
+	ttlMs;
 	/**
 	* @param fetcher - Function that fetches the integrations array from the registry API.
 	*                  Typically backed by api-client's IntegrationsService.getRegistry().
+	* @param options - Optional cache configuration (TTL).
 	*/
-	constructor(fetcher) {
+	constructor(fetcher, options = {}) {
 		this.fetcher = fetcher;
+		this.ttlMs = options.ttlMs ?? 6e4;
+	}
+	/** True when the cached index is absent or older than the TTL. */
+	isStale() {
+		if (!this.index) return true;
+		if (this.ttlMs <= 0) return true;
+		return Date.now() - this.loadedAt >= this.ttlMs;
 	}
 	/**
-	* Load the registry index. Uses cache if already loaded.
+	* Load the registry index. Returns the cached index while it's still within
+	* TTL; refetches once the cache is stale (or when `{ fresh: true }` is passed).
 	*/
-	async load() {
-		if (this.index) return this.index;
+	async load(options = {}) {
+		if (!options.fresh && this.index && !this.isStale()) return this.index;
 		const raw = await this.fetcher();
 		const integrations = {};
 		for (const entry of raw) {
@@ -31,20 +44,25 @@ var Registry = class {
 			version: 1,
 			integrations
 		};
+		this.loadedAt = Date.now();
 		return this.index;
 	}
 	/**
-	* Force reload the index (bypass cache).
+	* Force reload the index (bypass cache). Equivalent to `load({ fresh: true })`.
 	*/
 	async reload() {
 		this.index = null;
-		return this.load();
+		return this.load({ fresh: true });
 	}
 	/**
 	* Get a specific integration entry by name.
+	*
+	* @param fresh - When true, force a fresh fetch before reading (used by the
+	*                resolve-for-install path so a stale version list never blocks
+	*                a just-published version).
 	*/
-	async get(id) {
-		return (await this.load()).integrations[id];
+	async get(id, fresh = false) {
+		return (await this.load({ fresh })).integrations[id];
 	}
 	/**
 	* List all integrations in the registry.
@@ -83,10 +101,12 @@ var Resolver = class {
 	*
 	* @param name - Integration name (e.g. "discord")
 	* @param version - Specific version (e.g. "1.0.0") or undefined for latest
+	* @param options - Pass `{ fresh: true }` to bypass the registry cache
+	*                  (used by the install/reconcile path).
 	* @returns Resolved integration with repo URL and commit hash
 	*/
-	async resolve(id, version) {
-		const entry = await this.registry.get(id);
+	async resolve(id, version, options = {}) {
+		const entry = await this.registry.get(id, options.fresh);
 		if (!entry) throw new RegistryResolveError(`Integration "${id}" not found in registry`);
 		const resolvedVersion = version && version.length > 0 ? version : entry.latest;
 		if (!entry.versions.includes(resolvedVersion)) throw new RegistryResolveError(`Version "${resolvedVersion}" not found for integration "${id}". Available versions: ${entry.versions.join(", ")}`);
@@ -966,7 +986,7 @@ var IntegrationManager = class {
 				resolved = buildCustomResolved(name, customSource);
 				this.log.info(`Custom Connection install: ${name} from ${resolved.repository}@${resolved.commit}`);
 			} else {
-				resolved = await this.resolver.resolve(name, version);
+				resolved = await this.resolver.resolve(name, version, { fresh: true });
 				this.log.info(`Resolved ${name}@${resolved.version} from ${resolved.repository}`);
 			}
 			const installPath = await this.installer.install(resolved);
@@ -2157,4 +2177,4 @@ var IntegrationManagerAdapter = class {
 	}
 };
 //#endregion
-export { Installer, InstallerError, IntegrationManager, IntegrationManagerAdapter, LockManager, McpApplier, OpenClawApplier, Registry, RegistryResolveError, Resolver, StateManager, buildHookEnv, resolveInstallsForRuntime, runHook, runHookWithContext };
+export { DEFAULT_REGISTRY_TTL_MS, Installer, InstallerError, IntegrationManager, IntegrationManagerAdapter, LockManager, McpApplier, OpenClawApplier, Registry, RegistryResolveError, Resolver, StateManager, buildHookEnv, resolveInstallsForRuntime, runHook, runHookWithContext };

package/package.json

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