aimeat 1.2.0

package/dist/src/services/cache-cleanup.js

@@ -0,0 +1,123 @@
+/**
+ * Cache Cleanup Service — prevents unbounded storage growth from federated data.
+ * Runs hourly to prune expired entries.
+ *
+ * Scans memory entries by agent GAII, filtering for federated key prefixes
+ * (replica:, federated:, genesis:, _conflict_, expiring:) and removes entries
+ * older than their respective TTLs.
+ */
+import { logger } from '../utils/logger.js';
+/** Key prefixes used by federation data sync. */
+const FEDERATION_PREFIXES = ['federated:', 'replica:', 'genesis:', '_conflict_', 'expiring:'];
+/**
+ * Run a single cleanup cycle.
+ * Iterates over all agents, lists their memory entries by prefix,
+ * and removes entries older than the configured TTL.
+ */
+export async function runCleanupCycle(config, storage) {
+    const now = new Date();
+    const result = {
+        federatedRemoved: 0,
+        replicaRemoved: 0,
+        genesisRemoved: 0,
+        conflictRemoved: 0,
+        expiringRemoved: 0,
+        agentsScanned: 0,
+        cleanedAt: now.toISOString(),
+    };
+    // Cache TTL for federated/replica/genesis entries (from genesis sync config, fallback to 168h/7 days)
+    const cacheTtlHours = config.genesisMemoryCacheTtlHours || 168;
+    const cacheCutoff = new Date(now.getTime() - cacheTtlHours * 3_600_000);
+    // Conflict entries: 7-day fixed TTL
+    const conflictCutoff = new Date(now.getTime() - 7 * 24 * 3_600_000);
+    // Grace period for expiring entries (de-peering grace)
+    const graceCutoff = new Date(now.getTime() - config.depeeringGracePeriodHours * 3_600_000);
+    // Collect all agent GAIIs to scan their memory
+    let agentGaiis;
+    try {
+        const agents = await storage.listAgents();
+        agentGaiis = agents.map(a => a.gaii);
+    }
+    catch {
+        logger.warn('Cache cleanup: failed to list agents, skipping cycle');
+        return result;
+    }
+    for (const gaii of agentGaiis) {
+        result.agentsScanned++;
+        for (const prefix of FEDERATION_PREFIXES) {
+            try {
+                const entries = await storage.listMemory(gaii, { prefix });
+                for (const entry of entries) {
+                    const entryTime = new Date(entry.updatedAt);
+                    let shouldDelete = false;
+                    if (prefix === '_conflict_') {
+                        shouldDelete = entryTime < conflictCutoff;
+                    }
+                    else if (prefix === 'expiring:') {
+                        shouldDelete = entryTime < graceCutoff;
+                    }
+                    else {
+                        // federated:, replica:, genesis: — all use cache TTL
+                        shouldDelete = entryTime < cacheCutoff;
+                    }
+                    if (shouldDelete) {
+                        await storage.deleteMemory(gaii, entry.key);
+                        switch (prefix) {
+                            case 'federated:':
+                                result.federatedRemoved++;
+                                break;
+                            case 'replica:':
+                                result.replicaRemoved++;
+                                break;
+                            case 'genesis:':
+                                result.genesisRemoved++;
+                                break;
+                            case '_conflict_':
+                                result.conflictRemoved++;
+                                break;
+                            case 'expiring:':
+                                result.expiringRemoved++;
+                                break;
+                        }
+                    }
+                }
+            }
+            catch {
+                // listMemory with prefix may yield no results — that's expected
+            }
+        }
+    }
+    const totalRemoved = result.federatedRemoved + result.replicaRemoved +
+        result.genesisRemoved + result.conflictRemoved + result.expiringRemoved;
+    if (totalRemoved > 0) {
+        logger.info('Cache cleanup completed', {
+            federated: result.federatedRemoved,
+            replica: result.replicaRemoved,
+            genesis: result.genesisRemoved,
+            conflict: result.conflictRemoved,
+            expiring: result.expiringRemoved,
+            agentsScanned: result.agentsScanned,
+        });
+    }
+    return result;
+}
+/**
+ * Start the cache cleanup scheduler. Runs every hour.
+ * Returns the interval timer so it can be stopped on shutdown.
+ */
+export function startCacheCleanupJob(config, storage) {
+    const INTERVAL_MS = 60 * 60_000; // 1 hour
+    logger.info('Cache cleanup scheduler started (hourly)');
+    // Initial cleanup after 30s to avoid startup contention
+    setTimeout(() => {
+        runCleanupCycle(config, storage).catch(err => {
+            logger.error('Initial cache cleanup failed', { error: err.message });
+        });
+    }, 30_000);
+    return setInterval(() => {
+        runCleanupCycle(config, storage).catch(err => {
+            logger.error('Cache cleanup cycle failed', { error: err.message });
+        });
+    }, INTERVAL_MS);
+}
+//# sourceMappingURL=cache-cleanup.js.map

package/dist/src/services/cache-cleanup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-cleanup.js","sourceRoot":"","sources":["../../../src/services/cache-cleanup.ts"],"names":[],"mappings":"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"}

package/dist/src/services/catalogue-sync.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Catalogue Sync Service — outbound diff-based catalogue push to federation peers.
+ * Per RFC v1.6 §13.11.3 (delta sync) and §13.11.6 (triggering).
+ */
+import type { AimeatConfig } from '../config.js';
+import type { Storage } from '../storage/interface.js';
+import type { PeerInfo } from '../services/federation.js';
+/** Per-peer sync metadata. */
+export interface PeerSyncState {
+    lastSyncAt: string | null;
+    lastCatalogueHash: string | null;
+    consecutiveFailures: number;
+    lastError: string | null;
+}
+/** Get sync state for a peer (creates default if missing). */
+export declare function getPeerSyncState(peerId: string): PeerSyncState;
+/** Reset sync state for a peer (e.g. after re-peering). */
+export declare function resetPeerSyncState(peerId: string): void;
+export interface CatalogueSyncResult {
+    peer_node_id: string;
+    entries_sent: number;
+    incremental: boolean;
+    catalogue_hash: string;
+    success: boolean;
+    resync_required: boolean;
+    error?: string;
+}
+/**
+ * Sync catalogue to a single peer.
+ * 1. Read local CSMs where federate: true
+ * 2. If lastSyncAt exists: only include entries with updatedAt > lastSyncAt
+ * 3. Compute catalogue hash for verification
+ * 4. Sign payload with node Ed25519 key
+ * 5. POST to peer's /v1/federation/catalogue-sync
+ */
+export declare function syncCatalogueToPeer(peer: PeerInfo, config: AimeatConfig, storage: Storage): Promise<CatalogueSyncResult>;
+/**
+ * Sync catalogue to all active peers, respecting concurrent sync limit.
+ */
+export declare function syncCatalogueToAllPeers(config: AimeatConfig, storage: Storage, peers: Map<string, PeerInfo>): Promise<CatalogueSyncResult[]>;
+/**
+ * Enqueue catalogue sync for a specific peer to the replication queue.
+ */
+export declare function enqueueCatalogueSync(peerId: string, config: AimeatConfig, storage: Storage): Promise<string>;
+//# sourceMappingURL=catalogue-sync.d.ts.map

package/dist/src/services/catalogue-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalogue-sync.d.ts","sourceRoot":"","sources":["../../../src/services/catalogue-sync.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAM1D,8BAA8B;AAC9B,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAKD,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAO9D;AAED,2DAA2D;AAC3D,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,mBAAmB,CAAC,CAwI9B;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,GAC3B,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAqChC;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,MAAM,CAAC,CASjB"}

package/dist/src/services/catalogue-sync.js

@@ -0,0 +1,196 @@
+/**
+ * Catalogue Sync Service — outbound diff-based catalogue push to federation peers.
+ * Per RFC v1.6 §13.11.3 (delta sync) and §13.11.6 (triggering).
+ */
+import { sign } from '../auth/keypair.js';
+import { computeCatalogueHash } from '../utils/catalogue-hash.js';
+import { validateOutboundUrl } from '../utils/url-validator.js';
+import { logger } from '../utils/logger.js';
+/** In-memory sync state per peer. */
+const peerSyncStates = new Map();
+/** Get sync state for a peer (creates default if missing). */
+export function getPeerSyncState(peerId) {
+    let state = peerSyncStates.get(peerId);
+    if (!state) {
+        state = { lastSyncAt: null, lastCatalogueHash: null, consecutiveFailures: 0, lastError: null };
+        peerSyncStates.set(peerId, state);
+    }
+    return state;
+}
+/** Reset sync state for a peer (e.g. after re-peering). */
+export function resetPeerSyncState(peerId) {
+    peerSyncStates.delete(peerId);
+}
+/**
+ * Sync catalogue to a single peer.
+ * 1. Read local CSMs where federate: true
+ * 2. If lastSyncAt exists: only include entries with updatedAt > lastSyncAt
+ * 3. Compute catalogue hash for verification
+ * 4. Sign payload with node Ed25519 key
+ * 5. POST to peer's /v1/federation/catalogue-sync
+ */
+export async function syncCatalogueToPeer(peer, config, storage) {
+    const syncState = getPeerSyncState(peer.nodeId);
+    const catalogueHash = await computeCatalogueHash(storage);
+    try {
+        // 1. Read local CSMs where federate: true
+        const csms = await storage.listCsms();
+        const federableCsms = csms.filter(c => c.federate === true);
+        // 2. Gather all actions from federable CSMs
+        const allActions = await storage.listActions();
+        const federableActions = allActions.filter(action => {
+            // Include actions from agents belonging to federable CSMs
+            return federableCsms.some(csm => {
+                const def = csm.definition;
+                return action.category === def?.service?.type || action.tags.includes(`csm:${csm.name}`);
+            }) || action.tags.some(t => t.startsWith('federate:'));
+        });
+        // 3. Filter for delta sync if we have a lastSyncAt
+        let actionsToSync = federableActions;
+        const isIncremental = !!syncState.lastSyncAt;
+        if (isIncremental) {
+            const sinceDate = new Date(syncState.lastSyncAt);
+            actionsToSync = federableActions.filter(a => new Date(a.updatedAt) > sinceDate);
+        }
+        // 4. Build the payload
+        const payload = {
+            source_node: config.nodeId,
+            actions: actionsToSync.map(a => ({
+                id: a.id,
+                provider_gaii: a.providerGaii,
+                display_name: a.displayName,
+                description: a.description,
+                category: a.category,
+                input_schema: a.inputSchema,
+                output_schema: a.outputSchema,
+                pricing: {
+                    base_morsels: a.pricing.baseMorsels,
+                    per_unit: a.pricing.perUnit,
+                },
+                tags: a.tags,
+                semantic: a.semantic,
+                created_at: a.createdAt,
+                updated_at: a.updatedAt,
+            })),
+            since_timestamp: syncState.lastSyncAt,
+            catalogue_hash: catalogueHash,
+        };
+        // 5. Sign the payload
+        const nodeKey = await storage.getNodeKey();
+        let payloadSignature;
+        if (nodeKey?.privateKey) {
+            const signPayload = JSON.stringify({
+                source_node: payload.source_node,
+                actions: payload.actions,
+                since_timestamp: payload.since_timestamp,
+                catalogue_hash: payload.catalogue_hash,
+            });
+            payloadSignature = await sign(nodeKey.privateKey, signPayload);
+        }
+        // 6. SSRF validation
+        const urlCheck = await validateOutboundUrl(peer.url);
+        if (!urlCheck.valid) {
+            throw new Error(`SSRF blocked: ${urlCheck.reason}`);
+        }
+        // 7. POST to peer
+        const resp = await fetch(`${peer.url}/v1/federation/catalogue-sync`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ ...payload, signature: payloadSignature }),
+            signal: AbortSignal.timeout(config.federationTimeoutMs),
+        });
+        if (!resp.ok) {
+            const body = await resp.text().catch(() => '');
+            throw new Error(`Peer returned HTTP ${resp.status}: ${body}`);
+        }
+        const responseData = await resp.json();
+        const resyncRequired = responseData.data?.resync_required === true;
+        // Update sync state on success
+        syncState.lastSyncAt = new Date().toISOString();
+        syncState.lastCatalogueHash = catalogueHash;
+        syncState.consecutiveFailures = 0;
+        syncState.lastError = null;
+        logger.info(`Catalogue sync to peer ${peer.nodeId} completed`, {
+            entries_sent: actionsToSync.length,
+            incremental: isIncremental,
+            synced: responseData.data?.synced,
+            updated: responseData.data?.updated,
+            resync_required: resyncRequired,
+        });
+        return {
+            peer_node_id: peer.nodeId,
+            entries_sent: actionsToSync.length,
+            incremental: isIncremental,
+            catalogue_hash: catalogueHash,
+            success: true,
+            resync_required: resyncRequired,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : 'unknown error';
+        syncState.consecutiveFailures++;
+        syncState.lastError = msg;
+        logger.warn(`Catalogue sync to peer ${peer.nodeId} failed`, {
+            error: msg,
+            consecutiveFailures: syncState.consecutiveFailures,
+        });
+        return {
+            peer_node_id: peer.nodeId,
+            entries_sent: 0,
+            incremental: !!syncState.lastSyncAt,
+            catalogue_hash: '',
+            success: false,
+            resync_required: false,
+            error: msg,
+        };
+    }
+}
+/**
+ * Sync catalogue to all active peers, respecting concurrent sync limit.
+ */
+export async function syncCatalogueToAllPeers(config, storage, peers) {
+    const activePeers = [...peers.values()].filter(p => p.status === 'active');
+    if (activePeers.length === 0)
+        return [];
+    const results = [];
+    const concurrency = config.maxConcurrentSyncs;
+    // Process in batches of maxConcurrentSyncs
+    for (let i = 0; i < activePeers.length; i += concurrency) {
+        const batch = activePeers.slice(i, i + concurrency);
+        const batchResults = await Promise.allSettled(batch.map(peer => syncCatalogueToPeer(peer, config, storage)));
+        for (const result of batchResults) {
+            if (result.status === 'fulfilled') {
+                results.push(result.value);
+                // If resync_required, queue a full resync by resetting state
+                if (result.value.resync_required) {
+                    resetPeerSyncState(result.value.peer_node_id);
+                }
+            }
+            else {
+                results.push({
+                    peer_node_id: 'unknown',
+                    entries_sent: 0,
+                    incremental: false,
+                    catalogue_hash: '',
+                    success: false,
+                    resync_required: false,
+                    error: result.reason instanceof Error ? result.reason.message : String(result.reason),
+                });
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Enqueue catalogue sync for a specific peer to the replication queue.
+ */
+export async function enqueueCatalogueSync(peerId, config, storage) {
+    const id = await storage.enqueueReplication({
+        type: 'catalogue_sync',
+        targetPeers: [peerId],
+        payload: { trigger: 'manual', timestamp: new Date().toISOString() },
+        createdAt: new Date().toISOString(),
+    });
+    return id;
+}
+//# sourceMappingURL=catalogue-sync.js.map

package/dist/src/services/catalogue-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalogue-sync.js","sourceRoot":"","sources":["../../../src/services/catalogue-sync.ts"],"names":[],"mappings":"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"}

package/dist/src/services/component-registrar.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @file component-registrar.ts
+ * @description Service for registering, deleting, and fetching package components
+ *   via native AIMEAT storage APIs. Adapts PackageComponent content strings into
+ *   the format each storage repository expects. Used by the install, migration,
+ *   and uninstall flows in instances.ts.
+ * @structure
+ *   - registerComponent() — register a single component in its native storage
+ *   - deleteComponent() — remove a component from its native storage
+ *   - fetchComponentContent() — retrieve current content for hash comparison
+ *   - computeHash() — SHA-256 hash utility
+ *   - ComponentRegistrationResult — result type
+ * @usage
+ *   import { registerComponent, deleteComponent, fetchComponentContent, computeHash } from '../services/component-registrar.js';
+ * @version-history
+ *   v1.0.0 — 2026-03-15 — initial implementation
+ *   v1.1.0 — 2026-03-16 — fix memory component key management: use manifest key
+ *     instead of prefix-based lookup for delete/fetch; store keys as-is without
+ *     registeredAs prefix
+ */
+import type { Storage, PackageComponentType } from '../storage/interface.js';
+export interface ComponentRegistrationResult {
+    success: boolean;
+    componentId: string;
+    registeredAs: string;
+    error?: string;
+}
+export interface ComponentRegistrationInput {
+    componentId: string;
+    type: PackageComponentType;
+    registeredAs: string;
+    content: string;
+    label: string;
+    owner: string;
+    ownerGaii: string;
+    packageName: string;
+}
+/** Compute SHA-256 hash of content string */
+export declare function computeHash(content: string): string;
+/** Register a single component in its native storage repository */
+export declare function registerComponent(storage: Storage, input: ComponentRegistrationInput): Promise<ComponentRegistrationResult>;
+/** Delete a previously registered component from its native storage */
+export declare function deleteComponent(storage: Storage, type: PackageComponentType, registeredAs: string, ownerGaii: string): Promise<boolean>;
+/** Fetch current content string for a component (for hash comparison) */
+export declare function fetchComponentContent(storage: Storage, type: PackageComponentType, registeredAs: string, ownerGaii: string): Promise<string | null>;
+//# sourceMappingURL=component-registrar.d.ts.map

package/dist/src/services/component-registrar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-registrar.d.ts","sourceRoot":"","sources":["../../../src/services/component-registrar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAI7E,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,0BAA0B;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,oBAAoB,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAID,6CAA6C;AAC7C,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAID,mEAAmE;AACnE,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,2BAA2B,CAAC,CA+OtC;AAID,uEAAuE;AACvE,wBAAsB,eAAe,CACnC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,oBAAoB,EAC1B,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAiClB;AAID,yEAAyE;AACzE,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,oBAAoB,EAC1B,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyDxB"}