aismemory 0.6.2 → 0.7.0

package/dist/token-manager.js

@@ -0,0 +1,179 @@
+/**
+ * TokenManager: owns all in-memory token state for the aismemory client.
+ *
+ * - First `getCredentials()` authenticates and resolves agent identity;
+ *   concurrent callers during that first acquire share one in-flight promise.
+ * - A renewal is scheduled at 75% of the token's TTL. On success the
+ *   token/expiresAt swap in place — identity (agentId/tenantId) is resolved
+ *   once, on the very first acquire, and never re-resolved.
+ * - Renewal failures retry with exponential backoff (5s → 10s → 20s ...
+ *   capped at 300s, ±20% jitter) while the current token remains valid.
+ *   Backoff state (retryDelayMs/lastAttemptAt/lastError) is shared between
+ *   the background renewal loop and any on-demand `getCredentials()` call
+ *   made while the token is expired, so a burst of sequential calls during
+ *   an outage makes at most one fresh authenticate() attempt per backoff
+ *   window instead of one per call.
+ * - Once the current token hits its hard expiry with renewal still failing,
+ *   `getCredentials()` rejects with `AisUnreachableError` until the next
+ *   successful renewal — retries never stop, and recovery needs no restart.
+ * - No code path ever serializes the token to disk; it lives only in the
+ *   closure state below for the process lifetime.
+ * - `invalidate()` drops the current token (without touching backoff state)
+ *   so a caller that discovers the server rejected it mid-session — e.g. a
+ *   401 from a JWT_SECRET rotation, CORBOT-A5BBD580 — can force the next
+ *   `getCredentials()` to acquire a fresh one instead of re-serving the
+ *   rejected token.
+ */
+/**
+ * Thrown by `getCredentials()` once the current token has hard-expired and
+ * background renewal is still failing. Renewal keeps retrying in the
+ * background; the next successful renewal makes `getCredentials()` resolve
+ * again with no restart required.
+ */
+export class AisUnreachableError extends Error {
+}
+const RENEW_FRACTION = 0.75;
+const BACKOFF_BASE_MS = 5_000;
+const BACKOFF_CAP_MS = 300_000;
+export function createTokenManager(opts) {
+    const now = opts.now ?? Date.now;
+    let current = null;
+    // Tracked separately from `current` so `invalidate()` (which drops
+    // `current` to force a fresh acquire) does not also make `acquire()`
+    // re-resolve identity — identity is resolved once, on the very first
+    // acquire, and never re-resolved for the life of the manager (see module
+    // docstring). Set once, alongside `current`, on the first successful
+    // acquire; never cleared.
+    let resolvedIdentity = null;
+    let inFlight = null;
+    let timer = null;
+    let retryDelayMs = 0;
+    let lastAttemptAt = 0;
+    let hardExpiryEmitted = false;
+    let stopped = false;
+    let lastError = '';
+    function jitter(ms) {
+        return Math.round(ms * (0.8 + Math.random() * 0.4));
+    }
+    function schedule(delayMs, fn) {
+        if (stopped)
+            return;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(fn, delayMs);
+        timer.unref?.();
+    }
+    function scheduleRenewal(expiresAt) {
+        const ttlMs = new Date(expiresAt).getTime() - now();
+        schedule(Math.max(1_000, Math.floor(ttlMs * RENEW_FRACTION)), () => {
+            void renew();
+        });
+    }
+    /**
+     * Records a failed authenticate/resolveIdentity attempt into the shared
+     * backoff state, regardless of whether it came from the background renewal
+     * loop or from an on-demand `getCredentials()` call on an expired token.
+     * Escalates retryDelayMs, marks the attempt time (so callers can tell
+     * whether a fresh attempt is due), emits `renew.retry`, and — once — the
+     * `renew.hard_expiry` event when the current token has passed hard expiry.
+     */
+    function recordFailure(err) {
+        lastError = err instanceof Error ? err.message : String(err);
+        lastAttemptAt = now();
+        retryDelayMs = retryDelayMs === 0 ? BACKOFF_BASE_MS : Math.min(retryDelayMs * 2, BACKOFF_CAP_MS);
+        opts.onEvent?.('renew.retry', lastError);
+        if (current && new Date(current.expiresAt).getTime() <= now() && !hardExpiryEmitted) {
+            hardExpiryEmitted = true;
+            opts.onEvent?.('renew.hard_expiry', lastError);
+        }
+    }
+    async function acquire() {
+        const fresh = await opts.authenticate();
+        if (!Number.isFinite(new Date(fresh.expiresAt).getTime())) {
+            throw new Error(`TokenManager.acquire(): authenticate() returned an invalid expiresAt: ${JSON.stringify(fresh.expiresAt)}`);
+        }
+        // Identity is resolved only on the very first acquire; every later
+        // acquire (renewal, or a re-acquire after invalidate()) reuses the
+        // cached agentId/tenantId.
+        let agentId;
+        let tenantId;
+        if (resolvedIdentity) {
+            agentId = resolvedIdentity.agentId;
+            tenantId = resolvedIdentity.tenantId;
+        }
+        else {
+            const ids = await opts.resolveIdentity(fresh.token);
+            agentId = ids.agentId;
+            tenantId = ids.tenantId;
+            resolvedIdentity = { agentId, tenantId };
+        }
+        current = { token: fresh.token, expiresAt: fresh.expiresAt, agentId, tenantId };
+        retryDelayMs = 0;
+        hardExpiryEmitted = false;
+        scheduleRenewal(fresh.expiresAt);
+        return current;
+    }
+    async function renew() {
+        try {
+            await acquire();
+            opts.onEvent?.('renew.success');
+        }
+        catch (err) {
+            recordFailure(err);
+            schedule(jitter(retryDelayMs), () => {
+                void renew();
+            });
+        }
+    }
+    return {
+        async getCredentials() {
+            if (current && new Date(current.expiresAt).getTime() > now()) {
+                return current;
+            }
+            if (!inFlight) {
+                // The current token is missing or expired. If a prior attempt
+                // (from here or from the background renewal loop) failed and we're
+                // still inside its backoff window, don't make a fresh attempt —
+                // that would let a burst of sequential calls (e.g. several tool
+                // calls in one MCP chat turn) each hammer the auth endpoint during
+                // an outage, racing the properly-backed-off background timer and
+                // defeating the point of backoff. Fail fast with the last known
+                // error instead; the background timer (or the next call after the
+                // window elapses) makes the next real attempt.
+                if (retryDelayMs > 0 && now() - lastAttemptAt < retryDelayMs) {
+                    throw new AisUnreachableError(`AIS unreachable — renewing automatically; no action needed. Last error: ${lastError}`);
+                }
+                inFlight = acquire().finally(() => {
+                    inFlight = null;
+                });
+            }
+            try {
+                return await inFlight;
+            }
+            catch (err) {
+                recordFailure(err);
+                throw new AisUnreachableError(`AIS unreachable — renewing automatically; no action needed. Last error: ${lastError}`);
+            }
+        },
+        /**
+         * Drops the current token so the next `getCredentials()` must acquire a
+         * fresh one — used when the server itself rejects a still-time-valid
+         * token (e.g. a mid-session JWT_SECRET rotation, CORBOT-A5BBD580).
+         * Deliberately does NOT touch backoff bookkeeping (`retryDelayMs` /
+         * `lastAttemptAt`): a server that keeps rejecting tokens must not turn
+         * into an unthrottled hammer on the auth endpoint — `recordFailure`'s
+         * shared-backoff-window gate in `getCredentials()` still applies as-is.
+         * Does not cancel or reschedule the background renewal timer; a
+         * successful next acquire reschedules renewal exactly as it does today.
+         */
+        invalidate() {
+            current = null;
+        },
+        stop() {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+        },
+    };
+}
+//# sourceMappingURL=token-manager.js.map

package/dist/token-manager.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aismemory",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Persistent memory for AI agents. MCP server that connects to Agent Identity Service.",
   "mcpName": "ai.agentsandswarms/ais-memory",
   "type": "module",