@juspay/neurolink 9.41.0 → 9.42.1

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [9.42.1](https://github.com/juspay/neurolink/compare/v9.42.0...v9.42.1) (2026-04-02)
+
+## [9.42.0](https://github.com/juspay/neurolink/compare/v9.41.0...v9.42.0) (2026-04-01)
+
+### Features
+
+- **(proxy):** add OTLP observability, passthrough mode, and env-file support ([59ae70b](https://github.com/juspay/neurolink/commit/59ae70b9a33089f04addce63eb9e6151dcc97a0f))
+
 ## [9.41.0](https://github.com/juspay/neurolink/compare/v9.40.0...v9.41.0) (2026-03-30)
 
 ### Features

package/README.md

@@ -57,6 +57,7 @@ Extracted from production systems at Juspay and battle-tested at enterprise scal
 
 - **Memory** – Per-user condensed memory that persists across all conversations. Automatically retrieves and stores memory on each `generate()`/`stream()` call. Supports S3, Redis, and SQLite storage with LLM-powered condensation. → [Memory Guide](docs/features/memory.md)
 - **External TracerProvider Support** – Integrate NeuroLink with applications that already have OpenTelemetry instrumentation. Supports auto-detection and manual configuration. → [Observability Guide](docs/features/observability.md)
+- **Claude Proxy Telemetry** – Bootstrap a local OpenObserve + OTEL collector stack with `neurolink proxy telemetry setup`, import the maintained NeuroLink Proxy Observability dashboard, and inspect proxy logs, traces, metrics, cache reuse, and routing behavior. → [Claude Proxy Guide](docs/features/claude-proxy.md) | [Proxy Observability Guide](docs/features/claude-proxy-observability.md)
 - **Server Adapters** – Deploy NeuroLink as an HTTP API server with your framework of choice (Hono, Express, Fastify, Koa). Full CLI support with `serve` and `server` commands for foreground/background modes, route management, and OpenAPI generation. → [Server Adapters Guide](docs/guides/server-adapters/index.md)
 - **Title Generation Events** – Emit real-time events when conversation titles are auto-generated. Listen to `conversation:titleGenerated` for session tracking. → [Conversation Memory Guide](docs/conversation-memory.md#title-generation-events)
 - **Custom Title Prompts** – Customize conversation title generation with `NEUROLINK_TITLE_PROMPT` environment variable. Use `${userMessage}` placeholder for dynamic prompts. → [Conversation Memory Guide](docs/conversation-memory.md#customizing-the-title-prompt)
@@ -599,6 +600,11 @@ npx @juspay/neurolink generate "Draft release notes" \
 # RAG: Ask questions about your docs (auto-chunks, embeds, searches)
 npx @juspay/neurolink generate "What are the key features?" \
   --rag-files ./docs/guide.md ./docs/api.md --rag-strategy markdown
+
+# Claude proxy + local OpenObserve dashboard
+npx @juspay/neurolink proxy setup
+npx @juspay/neurolink proxy telemetry setup
+npx @juspay/neurolink proxy status --format json
 ```
 
 ```typescript
@@ -677,7 +683,7 @@ Full command and API breakdown lives in [`docs/cli/commands.md`](docs/cli/comman
 | **Quality & governance** | Auto-evaluation engine (Q3), guardrails middleware (Q4), HITL workflows (Q4), audit logging.                             |
 | **Memory & context**     | Conversation memory, Redis history export (Q4), context summarization (Q4).                                              |
 | **CLI tooling**          | Loop sessions (Q3), setup wizard, config validation, Redis auto-detect, JSON output.                                     |
-| **Enterprise ops**       | Proxy support, regional routing (Q3), telemetry hooks, configuration management.                                         |
+| **Enterprise ops**       | Proxy support, regional routing (Q3), telemetry hooks, local OpenObserve dashboard setup, configuration management.      |
 | **Tool ecosystem**       | MCP auto discovery, HTTP/stdio/SSE/WebSocket transports, LiteLLM hub access, SageMaker custom deployment, web search.    |
 
 ## Documentation Map

package/dist/auth/anthropicOAuth.d.ts

@@ -43,13 +43,28 @@ export declare const DEFAULT_SCOPES: readonly string[];
 /**
  * User-Agent string to spoof Claude CLI
  */
-export declare const CLAUDE_CLI_USER_AGENT = "claude-cli/2.1.2 (external, cli)";
+export declare const CLAUDE_CODE_VERSION = "2.1.87.6d6";
+export declare const CLAUDE_CODE_ENTRYPOINT = "sdk-cli";
+export declare const CLAUDE_CLI_USER_AGENT = "claude-cli/2.1.87 (external, sdk-cli)";
+export type ClaudeCodeIdentity = {
+    deviceId: string;
+    accountUuid: string;
+    sessionId: string;
+    metadataUserId: string;
+};
+export declare function parseClaudeCodeUserId(userId: unknown): ClaudeCodeIdentity | null;
+export declare function getOrCreateClaudeCodeIdentity(seed: string, options?: {
+    existingUserId?: unknown;
+    preferredSessionId?: string;
+}): ClaudeCodeIdentity;
+export declare function purgeExpiredClaudeCodeIdentities(now?: number): number;
+export declare function buildStableClaudeCodeBillingHeader(originalText?: string): string;
 /**
  * Required beta headers for OAuth API requests.
  * The "oauth-2025-04-20" header is CRITICAL for OAuth authentication.
- * The "interleaved-thinking-2025-05-14" enables extended thinking.
  */
-export declare const OAUTH_BETA_HEADERS = "oauth-2025-04-20,interleaved-thinking-2025-05-14";
+export declare const OAUTH_BETA_HEADERS = "oauth-2025-04-20";
+export declare const CLAUDE_CODE_OAUTH_BETAS: readonly ["oauth-2025-04-20", "claude-code-20250219", "context-management-2025-06-27", "prompt-caching-scope-2026-01-05", "advanced-tool-use-2025-11-20", "effort-2025-11-24"];
 /**
  * Tool name prefix required for OAuth API requests
  */

package/dist/auth/anthropicOAuth.js

@@ -14,7 +14,7 @@
  *
  * @module auth/anthropicOAuth
  */
-import { createHash, randomBytes } from "crypto";
+import { createHash, createHmac, randomBytes, randomUUID } from "crypto";
 import { createServer } from "http";
 import { OAuthError, OAuthConfigurationError, OAuthTokenExchangeError, OAuthTokenRefreshError, OAuthTokenRevocationError, OAuthCallbackServerError, } from "../types/errors.js";
 import { logger } from "../utils/logger.js";
@@ -73,13 +73,158 @@ export const DEFAULT_SCOPES = [
 /**
  * User-Agent string to spoof Claude CLI
  */
-export const CLAUDE_CLI_USER_AGENT = "claude-cli/2.1.2 (external, cli)";
+export const CLAUDE_CODE_VERSION = "2.1.87.6d6";
+export const CLAUDE_CODE_ENTRYPOINT = "sdk-cli";
+export const CLAUDE_CLI_USER_AGENT = "claude-cli/2.1.87 (external, sdk-cli)";
+const CLAUDE_CODE_IDENTITY_TTL_MS = 3_600_000;
+const CLAUDE_CODE_IDENTITY_CACHE_MAX_ENTRIES = 1024;
+const CLAUDE_CODE_IDENTITY_NAMESPACE = "neurolink-claude-code-identity-v1";
+const claudeCodeIdentityCache = new Map();
+function stableIdentityDigest(input) {
+    // These identifiers are deterministic pseudonyms for Claude Code metadata,
+    // not password hashes or authentication secrets.
+    return createHmac("sha256", CLAUDE_CODE_IDENTITY_NAMESPACE)
+        .update(input)
+        .digest("hex");
+}
+function hexToUuid(hex) {
+    const trimmed = hex.replace(/-/g, "").slice(0, 32).padEnd(32, "0");
+    return `${trimmed.slice(0, 8)}-${trimmed.slice(8, 12)}-${trimmed.slice(12, 16)}-${trimmed.slice(16, 20)}-${trimmed.slice(20, 32)}`;
+}
+function isUuid(value) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
+}
+function buildMetadataUserId(identity) {
+    return JSON.stringify({
+        device_id: identity.deviceId,
+        account_uuid: identity.accountUuid,
+        session_id: identity.sessionId,
+    });
+}
+export function parseClaudeCodeUserId(userId) {
+    if (typeof userId !== "string") {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(userId);
+        if (typeof parsed.device_id !== "string" ||
+            !/^[0-9a-f]{64}$/i.test(parsed.device_id) ||
+            typeof parsed.account_uuid !== "string" ||
+            !isUuid(parsed.account_uuid) ||
+            typeof parsed.session_id !== "string" ||
+            !isUuid(parsed.session_id)) {
+            return null;
+        }
+        return {
+            deviceId: parsed.device_id,
+            accountUuid: parsed.account_uuid,
+            sessionId: parsed.session_id,
+            metadataUserId: buildMetadataUserId({
+                deviceId: parsed.device_id,
+                accountUuid: parsed.account_uuid,
+                sessionId: parsed.session_id,
+            }),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function getOrCreateClaudeCodeIdentity(seed, options) {
+    const parsedExisting = parseClaudeCodeUserId(options?.existingUserId);
+    if (parsedExisting) {
+        if (options?.preferredSessionId && isUuid(options.preferredSessionId)) {
+            return {
+                deviceId: parsedExisting.deviceId,
+                accountUuid: parsedExisting.accountUuid,
+                sessionId: options.preferredSessionId,
+                metadataUserId: buildMetadataUserId({
+                    deviceId: parsedExisting.deviceId,
+                    accountUuid: parsedExisting.accountUuid,
+                    sessionId: options.preferredSessionId,
+                }),
+            };
+        }
+        return parsedExisting;
+    }
+    const now = Date.now();
+    const cacheKey = seed || "default";
+    const cached = claudeCodeIdentityCache.get(cacheKey);
+    if (cached && cached.expiresAt > now) {
+        if (options?.preferredSessionId && isUuid(options.preferredSessionId)) {
+            return {
+                deviceId: cached.deviceId,
+                accountUuid: cached.accountUuid,
+                sessionId: options.preferredSessionId,
+                metadataUserId: buildMetadataUserId({
+                    deviceId: cached.deviceId,
+                    accountUuid: cached.accountUuid,
+                    sessionId: options.preferredSessionId,
+                }),
+            };
+        }
+        return cached;
+    }
+    const deviceId = stableIdentityDigest(`${cacheKey}:device`);
+    const accountUuid = hexToUuid(stableIdentityDigest(`${cacheKey}:account`));
+    const sessionId = options?.preferredSessionId && isUuid(options.preferredSessionId)
+        ? options.preferredSessionId
+        : randomUUID();
+    const identity = {
+        deviceId,
+        accountUuid,
+        sessionId,
+        metadataUserId: buildMetadataUserId({
+            deviceId,
+            accountUuid,
+            sessionId,
+        }),
+        expiresAt: now + CLAUDE_CODE_IDENTITY_TTL_MS,
+    };
+    enforceClaudeCodeIdentityCacheLimit(now);
+    claudeCodeIdentityCache.set(cacheKey, identity);
+    return identity;
+}
+export function purgeExpiredClaudeCodeIdentities(now = Date.now()) {
+    let removed = 0;
+    for (const [cacheKey, identity] of claudeCodeIdentityCache.entries()) {
+        if (identity.expiresAt <= now) {
+            claudeCodeIdentityCache.delete(cacheKey);
+            removed += 1;
+        }
+    }
+    return removed;
+}
+function enforceClaudeCodeIdentityCacheLimit(now = Date.now()) {
+    purgeExpiredClaudeCodeIdentities(now);
+    while (claudeCodeIdentityCache.size >= CLAUDE_CODE_IDENTITY_CACHE_MAX_ENTRIES) {
+        const oldestKey = claudeCodeIdentityCache.keys().next().value;
+        if (!oldestKey) {
+            break;
+        }
+        claudeCodeIdentityCache.delete(oldestKey);
+    }
+}
+export function buildStableClaudeCodeBillingHeader(originalText) {
+    const version = originalText?.match(/cc_version=([^;]+)/)?.[1]?.trim() ||
+        CLAUDE_CODE_VERSION;
+    const entrypoint = originalText?.match(/cc_entrypoint=([^;]+)/)?.[1]?.trim() ||
+        CLAUDE_CODE_ENTRYPOINT;
+    return `x-anthropic-billing-header: cc_version=${version}; cc_entrypoint=${entrypoint}; cch=00000;`;
+}
 /**
  * Required beta headers for OAuth API requests.
  * The "oauth-2025-04-20" header is CRITICAL for OAuth authentication.
- * The "interleaved-thinking-2025-05-14" enables extended thinking.
  */
-export const OAUTH_BETA_HEADERS = "oauth-2025-04-20,interleaved-thinking-2025-05-14";
+export const OAUTH_BETA_HEADERS = "oauth-2025-04-20";
+export const CLAUDE_CODE_OAUTH_BETAS = [
+    "oauth-2025-04-20",
+    "claude-code-20250219",
+    "context-management-2025-06-27",
+    "prompt-caching-scope-2026-01-05",
+    "advanced-tool-use-2025-11-20",
+    "effort-2025-11-24",
+];
 /**
  * Tool name prefix required for OAuth API requests
  */

package/dist/auth/providers/firebase.js

@@ -60,8 +60,12 @@ export class FirebaseAuthProvider extends BaseAuthProvider {
             await this.initialize();
         }
         try {
+            const jwks = this.jwks;
+            if (!jwks) {
+                throw AuthError.create("PROVIDER_INIT_FAILED", "Firebase JWKS was not initialized", { details: { provider: "firebase" } });
+            }
             // Verify the token using Google's public keys
-            const { payload } = await jose.jwtVerify(token, this.jwks, {
+            const { payload } = await jose.jwtVerify(token, jwks, {
                 issuer: `https://securetoken.google.com/${this.projectId}`,
                 audience: this.projectId,
             });

package/dist/auth/providers/jwt.js

@@ -92,6 +92,10 @@ export class JWTProvider extends BaseAuthProvider {
             await this.initialize();
         }
         try {
+            const keyObject = this.keyObject;
+            if (!keyObject) {
+                throw AuthError.create("PROVIDER_INIT_FAILED", "JWT verification key was not initialized", { details: { provider: "jwt" } });
+            }
             const verifyOptions = {};
             if (this.algorithms.length > 0) {
                 verifyOptions.algorithms = this
@@ -103,7 +107,7 @@ export class JWTProvider extends BaseAuthProvider {
             if (this.audience) {
                 verifyOptions.audience = this.audience;
             }
-            const { payload } = await jose.jwtVerify(token, this.keyObject, verifyOptions);
+            const { payload } = await jose.jwtVerify(token, keyObject, verifyOptions);
             // Reject tokens without a non-empty sub claim
             if (!payload.sub) {
                 return {

package/dist/auth/providers/workos.js

@@ -65,8 +65,12 @@ export class WorkOSProvider extends BaseAuthProvider {
             await this.initialize();
         }
         try {
+            const jwks = this.jwks;
+            if (!jwks) {
+                throw AuthError.create("PROVIDER_INIT_FAILED", "WorkOS JWKS was not initialized", { details: { provider: "workos" } });
+            }
             // Verify the JWT
-            const { payload } = await jose.jwtVerify(token, this.jwks, {
+            const { payload } = await jose.jwtVerify(token, jwks, {
                 audience: this.clientId,
             });
             // Enforce organizationId if configured

package/dist/auth/sessionManager.d.ts

@@ -46,7 +46,7 @@ export declare class MemorySessionStorage implements SessionManagerStorage {
  * Redis session storage
  *
  * Distributed session storage using Redis. Suitable for multi-instance
- * deployments. Requires ioredis or similar Redis client.
+ * deployments. Requires the "redis" (node-redis) package.
  *
  * Note: Redis client must be provided or configured via environment.
  */

package/dist/auth/sessionManager.js

@@ -1,4 +1,5 @@
 // src/lib/auth/sessionManager.ts
+import { withTimeout } from "../utils/async/withTimeout.js";
 import { logger } from "../utils/logger.js";
 /** Mask an identifier for safe logging: show first 4 chars + "***" */
 function maskId(id) {
@@ -7,6 +8,7 @@ function maskId(id) {
     }
     return `${id.slice(0, 4)}***`;
 }
+const REDIS_CONNECT_TIMEOUT_MS = 5000;
 /**
  * In-memory session storage
  *
@@ -31,10 +33,12 @@ export class MemorySessionStorage {
     async set(session) {
         this.sessions.set(session.id, session);
         // Track user's sessions
-        if (!this.userSessions.has(session.user.id)) {
-            this.userSessions.set(session.user.id, new Set());
+        let sessionIds = this.userSessions.get(session.user.id);
+        if (!sessionIds) {
+            sessionIds = new Set();
+            this.userSessions.set(session.user.id, sessionIds);
         }
-        this.userSessions.get(session.user.id).add(session.id);
+        sessionIds.add(session.id);
     }
     async delete(sessionId) {
         const session = this.sessions.get(sessionId);
@@ -84,7 +88,7 @@ export class MemorySessionStorage {
  * Redis session storage
  *
  * Distributed session storage using Redis. Suitable for multi-instance
- * deployments. Requires ioredis or similar Redis client.
+ * deployments. Requires the "redis" (node-redis) package.
  *
  * Note: Redis client must be provided or configured via environment.
  */
@@ -111,16 +115,25 @@ export class RedisSessionStorage {
     async createClient() {
         try {
             // Use variable indirection to prevent TypeScript from resolving the module at compile time
-            const moduleName = "ioredis";
-            const ioredis = await import(/* @vite-ignore */ moduleName);
-            const Redis = ioredis.default || ioredis.Redis;
-            this.client = new Redis(this.redisUrl);
-            return this.client;
+            const moduleName = "redis";
+            const redisModule = (await import(
+            /* @vite-ignore */ moduleName));
+            const client = redisModule.createClient({
+                url: this.redisUrl,
+            });
+            client.on("error", (err) => {
+                logger.error("Redis session client error:", err.message);
+            });
+            await withTimeout(client.connect(), REDIS_CONNECT_TIMEOUT_MS, `Redis session client connect timed out after ${REDIS_CONNECT_TIMEOUT_MS}ms`);
+            this.client = client;
+            return client;
         }
-        catch {
+        catch (error) {
             this.initPromise = null;
-            logger.error('Redis client (ioredis) not available. Install ioredis package and ensure Redis is reachable when using storage: "redis".');
-            throw new Error("Redis client not available");
+            logger.error('Redis client not available. Ensure the "redis" package is installed and Redis is reachable when using storage: "redis".');
+            throw error instanceof Error
+                ? error
+                : new Error("Redis client not available");
         }
     }
     sessionKey(sessionId) {
@@ -136,6 +149,13 @@ export class RedisSessionStorage {
             if (!data) {
                 return null;
             }
+            if (typeof data !== "string") {
+                logger.warn("Unexpected Redis session payload type", {
+                    sessionId: maskId(sessionId),
+                    type: typeof data,
+                });
+                return null;
+            }
             const session = JSON.parse(data);
             // Parse dates
             session.createdAt = new Date(session.createdAt);
@@ -143,7 +163,7 @@ export class RedisSessionStorage {
                 session.expiresAt = new Date(session.expiresAt);
             }
             // Check expiration
-            if (new Date() > session.expiresAt) {
+            if (session.expiresAt && new Date() > session.expiresAt) {
                 await this.delete(sessionId);
                 return null;
             }
@@ -162,9 +182,9 @@ export class RedisSessionStorage {
                 ? Math.max(1, Math.floor((session.expiresAt.getTime() - Date.now()) / 1000))
                 : this.ttl;
             // Store session
-            await client.setex(this.sessionKey(session.id), ttlSeconds, JSON.stringify(session));
+            await client.setEx(this.sessionKey(session.id), ttlSeconds, JSON.stringify(session));
             // Track user's sessions
-            await client.sadd(this.userSessionsKey(session.user.id), session.id);
+            await client.sAdd(this.userSessionsKey(session.user.id), session.id);
             await client.expire(this.userSessionsKey(session.user.id), this.ttl);
         }
         catch (error) {
@@ -180,13 +200,21 @@ export class RedisSessionStorage {
             // recursion for expired sessions.
             const data = await client.get(this.sessionKey(sessionId));
             if (data) {
-                try {
-                    const session = JSON.parse(data);
-                    await client.srem(this.userSessionsKey(session.user.id), sessionId);
+                if (typeof data !== "string") {
+                    logger.warn("Unexpected Redis session payload type during delete", {
+                        sessionId: maskId(sessionId),
+                        type: typeof data,
+                    });
                 }
-                catch {
-                    // If parsing fails, we still delete the key below
-                    logger.warn(`Failed to parse session data for cleanup: ${maskId(sessionId)}`);
+                else {
+                    try {
+                        const session = JSON.parse(data);
+                        await client.sRem(this.userSessionsKey(session.user.id), sessionId);
+                    }
+                    catch {
+                        // If parsing fails, we still delete the key below
+                        logger.warn(`Failed to parse session data for cleanup: ${maskId(sessionId)}`);
+                    }
                 }
             }
             await client.del(this.sessionKey(sessionId));
@@ -198,7 +226,7 @@ export class RedisSessionStorage {
     async getUserSessions(userId) {
         try {
             const client = await this.getClient();
-            const sessionIds = await client.smembers(this.userSessionsKey(userId));
+            const sessionIds = await client.sMembers(this.userSessionsKey(userId));
             const sessions = [];
             for (const sessionId of sessionIds) {
                 const session = await this.get(sessionId);
@@ -216,7 +244,7 @@ export class RedisSessionStorage {
     async deleteUserSessions(userId) {
         try {
             const client = await this.getClient();
-            const sessionIds = await client.smembers(this.userSessionsKey(userId));
+            const sessionIds = await client.sMembers(this.userSessionsKey(userId));
             for (const sessionId of sessionIds) {
                 await client.del(this.sessionKey(sessionId));
             }
@@ -232,10 +260,13 @@ export class RedisSessionStorage {
             // Use SCAN instead of KEYS to avoid blocking Redis in production
             let cursor = "0";
             do {
-                const [nextCursor, keys] = await client.scan(cursor, "MATCH", `${this.prefix}*`, "COUNT", "100");
-                cursor = nextCursor;
-                if (keys.length > 0) {
-                    await client.del(...keys);
+                const result = await client.scan(cursor, {
+                    MATCH: `${this.prefix}*`,
+                    COUNT: 100,
+                });
+                cursor = result.cursor;
+                if (result.keys.length > 0) {
+                    await client.del(result.keys);
                 }
             } while (cursor !== "0");
         }