NeuroLink Review Fixes Documentation

Branch: feat/models-observability-rag-landing-review-fixes Date: 2026-02-28 Total Files Changed: 26 Total Lines Changed: +2,876 / -1,524

1. Executive Summary

This document covers 11 implementation tasks addressing 4 P0 critical bugs, 5 P1 high-priority improvements, and 2 P2 medium-priority refactors identified during code review of the NeuroLink SDK. All fixes were implemented across 26 source files spanning the core SDK, 11 provider implementations, 5 MCP modules, and utility layers.

Key outcomes:

P0 bugs: Double process spawn eliminated, restart timer leak fixed, cost estimation accuracy improved from ~5x error to per-model pricing, tool I/O size reporting corrected, SSE/WebSocket headers now forwarded, and validateClientConfig no longer rejects valid HTTP configs.
P1 improvements: Typed error hierarchy added to 3 providers (Azure, Mistral, HuggingFace), maxRetries:0 added to 5 providers, ENOTFOUND marked non-retryable, stream timeout composition + abort differentiation implemented, OTel stream/generate parity achieved, circuit breaker timer + signal handler leaks fixed.
P2 refactors: resolveTools() extracted to BaseProvider eliminating 14 duplicated code blocks across providers, dead code and debug artifacts removed.

2. P0 Bug Fixes (Critical)

P0-1: Double Process Spawn in stdio Transport

Issue: MCPClientFactory.createClient() spawned a child process via spawn() and then StdioClientTransport spawned a second one internally, resulting in orphaned zombie processes.

Root Cause: The factory manually called spawn() before passing the config to StdioClientTransport, which also calls spawn() internally. This created two child processes for every stdio MCP server.

Fix Applied: Removed the manual spawn() call from MCPClientFactory. Now only StdioClientTransport spawns the process. The factory accesses the process reference from the transport instance after connection via transport.stderr for logging.

Files Changed:

src/lib/mcp/mcpClientFactory.ts (+449/-449 total with OTel changes)

Verification: PASS

P0-2: Restart Timer Never Cleared

Issue: When ExternalServerManager.scheduleRestart() fired, the restartTimer reference was never cleared (= undefined), causing the guard if (instance.restartTimer) return to permanently block future restarts.

Root Cause: The setTimeout callback did not reset instance.restartTimer = undefined at the start of execution. After the timer fires, the reference remains set to the expired timer ID.

Fix Applied: Added instance.restartTimer = undefined; as the first line inside the setTimeout callback in scheduleRestart().

Files Changed:

src/lib/mcp/externalServerManager.ts (line ~491 in diff)

Verification: PASS

P0-3: Inaccurate Cost Estimation (5x Error)

Issue: Cost estimation used rough multipliers that could be off by 5x or more for some models. There was no per-model pricing table.

Root Cause: The estimateCost() function used generic provider-level multipliers rather than accurate per-model pricing data.

Fix Applied: Introduced calculateCost() from a new src/lib/utils/pricing.ts module with per-model pricing tables. Integrated into both BaseProvider.generate() and GenerationHandler to record accurate gen_ai.cost_usd span attributes.

Files Changed:

src/lib/core/baseProvider.ts (lines ~1095-1112) -- calculateCost() integration in generate path
src/lib/core/modules/GenerationHandler.ts (lines ~444-473) -- calculateCost() integration in GenerationHandler

Key Code:

// In baseProvider.ts generate() path:
if (enhancedResult?.usage) {
  span.setAttribute(
    "gen_ai.cost_usd",
    calculateCost(
      this.providerName,
      this.modelName || options.model || "",
      enhancedResult.usage,
    ),
  );
}

Verification: PASS

P0-4a: tool.input_size/output_size Reporting Truncated Length

Issue: Tool input/output size OTel attributes were reporting the length of truncated strings rather than actual full size.

Root Cause: The tool.result_size and tool.args attributes were recorded after .substring(0, 4096) truncation.

Fix Applied: In GenerationHandler.ts, tool result events now capture tool.result_size from the full result string length before truncation, and tool.args is truncated separately for the attribute value while preserving full size.

Files Changed:

src/lib/core/modules/GenerationHandler.ts (lines ~205-236 in onStepFinish)

Key Code:

// Record full size, truncate only the preview
const resultStr = typeof tr === "string" ? tr : JSON.stringify(tr ?? "");
activeSpan.addEvent("gen_ai.tool.result", {
  "tool.index": i,
  "tool.result_preview": resultStr.substring(0, 4096),
  "tool.result_size": resultStr.length, // Full size, not truncated
});

Verification: PASS

P0-4b: SSE/WebSocket Headers Silently Ignored

Issue: When configuring SSE or WebSocket MCP transports, custom headers (e.g., Authorization: Bearer ...) were silently ignored, causing authentication failures.

Root Cause: The MCPClientFactory.createHTTPTransport() and related methods did not forward config.headers to the underlying SSE/WebSocket transport constructors.

Fix Applied: Headers are now properly forwarded from the config to all HTTP-based transport types (SSE, WebSocket, Streamable HTTP) in mcpClientFactory.ts.

Files Changed:

src/lib/mcp/mcpClientFactory.ts

Verification: PASS

P0-4c: validateClientConfig Rejecting Valid HTTP Configs

Issue: The validateClientConfig() function required command for all transport types, incorrectly rejecting valid HTTP/SSE/WebSocket configs that only have url.

Root Cause: Validation logic checked for config.command without considering that HTTP-based transports use config.url instead.

Fix Applied: Updated validateClientConfig() to accept configs with either command (for stdio) or url (for HTTP/SSE/WebSocket) based on the transport type.

Files Changed:

src/lib/mcp/mcpClientFactory.ts

Verification: PASS

3. P1 High Priority Fixes

P1-1: Typed Errors Missing in Azure/Mistral/HuggingFace

Issue: Azure, Mistral, and HuggingFace providers returned generic Error instances from formatProviderError(), making it impossible for callers to distinguish authentication errors from rate limits, network failures, or invalid models.

Root Cause: These three providers did not use the typed error hierarchy (AuthenticationError, RateLimitError, NetworkError, InvalidModelError, ProviderError) that OpenAI, Anthropic, and other providers already used.

Fix Applied: Rewrote formatProviderError() in all three providers to return typed errors based on HTTP status codes and error message patterns:

401/403 or auth-related messages -> AuthenticationError
429 or rate limit messages -> RateLimitError
ECONNREFUSED/ENOTFOUND/ETIMEDOUT -> NetworkError
TimeoutError -> NetworkError
Model not found -> InvalidModelError
All others -> ProviderError

Files Changed:

src/lib/providers/azureOpenai.ts (+85/-21) -- Full formatProviderError() rewrite
src/lib/providers/mistral.ts (+62/-21) -- Full formatProviderError() rewrite
src/lib/providers/huggingFace.ts (+70/-36) -- Full formatProviderError() rewrite, removed emoji prefixes

Key Pattern (Azure example):

protected formatProviderError(error: unknown): Error {
  if (error instanceof TimeoutError) {
    return new NetworkError(error.message, this.providerName);
  }
  // ... status code / message checks ...
  if (statusCode === 401 || statusCode === 403 || message.includes("401")) {
    return new AuthenticationError(
      "Invalid Azure OpenAI API key or endpoint.",
      this.providerName,
    );
  }
  // ... rate limit, network, model checks ...
  return new ProviderError(`Azure OpenAI error: ${message}`, this.providerName);
}

Verification: PASS

P1-2: maxRetries:0 Missing from 5 Providers + ENOTFOUND Non-Retryable

Issue: Five providers (Azure, Google AI Studio, HuggingFace, Mistral, OpenAI Compatible) did not set maxRetries: 0 in their streamText() calls, allowing the Vercel AI SDK to perform invisible internal retries that bypassed NeuroLink's OTel-instrumented retry logic. Additionally, ENOTFOUND (DNS failure) was treated as retryable in the HTTP retry handler.

Root Cause: When these providers were initially implemented, the maxRetries: 0 convention (established in NL11) was not applied. The HTTP retry handler included ENOTFOUND in its retryable error codes list.

Fix Applied:

Added maxRetries: 0 to streamText() calls in: Azure, Google AI Studio, HuggingFace, Mistral, OpenAI Compatible.
Removed ENOTFOUND from isRetryableHTTPError() in httpRetryHandler.ts since DNS failures are permanent (the hostname does not exist).
Updated isRetryableProviderError() in providerRetry.ts to also exclude ENOTFOUND.

Files Changed:

src/lib/providers/azureOpenai.ts (line ~196) -- Added maxRetries: 0
src/lib/providers/googleAiStudio.ts (line ~594) -- Added maxRetries: 0
src/lib/providers/huggingFace.ts (line ~191) -- Added maxRetries: 0
src/lib/providers/mistral.ts (line ~102) -- Added maxRetries: 0
src/lib/providers/openaiCompatible.ts (line ~249) -- Added maxRetries: 0
src/lib/mcp/httpRetryHandler.ts -- Removed ENOTFOUND from retryable codes, fixed logger to use mcpLogger

Verification: PASS

P1-3: Stream Timeout Composition + Abort Differentiation

Issue: The stream path in BaseProvider.stream() did not compose timeout and user-provided abort signals the way generate() did. Abort errors were treated as failures with ERROR status in OTel spans.

Root Cause: The stream() method was missing the createTimeoutController() + composeAbortSignals() pattern already present in generate(). The catch block did not differentiate between abort errors (expected cancellation) and real errors.

Fix Applied:

Added timeout controller creation and signal composition at the top of BaseProvider.stream(), mirroring the generate() path.
In the catch block, added isAbortError(error) check: abort errors get SpanStatusCode.OK and info-level logging; real errors continue to get SpanStatusCode.ERROR.
Added timeoutController?.cleanup() in the finally block.

Files Changed:

src/lib/core/baseProvider.ts (lines ~184-200 for signal composition, lines ~304-317 for abort differentiation)

Key Code:

// Compose timeout signal with user-provided abort signal
const timeoutController = createTimeoutController(options.timeout, this.providerName, "stream");
const composedSignal = composeAbortSignals(options.abortSignal, timeoutController?.controller.signal);
if (composedSignal) {
  options = { ...options, abortSignal: composedSignal };
}

// In catch block:
if (isAbortError(error)) {
  span.setStatus({ code: SpanStatusCode.OK });
  logger.info(`Stream aborted for ${this.providerName}`, { ... });
} else {
  span.setStatus({ code: SpanStatusCode.ERROR, message: ... });
}

Verification: PASS

P1-4: OTel Stream/Generate Parity

Issue: The stream path was missing many OTel span attributes and child spans that the generate path had, creating an observability gap. Specifically: middleware count, generation config (temperature/maxTokens/maxSteps), cache tokens, cost estimates, TTFC (Time-To-First-Chunk), chunk metrics, input preview, generate path indicator, mem0 spans, conversation store spans, budget check spans, compaction spans, provider fallback chain recording.

Root Cause: Stream support was added after the generate path, and OTel instrumentation was not mirrored.

Fix Applied: Comprehensive OTel additions across multiple files:

BaseProvider (stream):

Added gen_ai.middleware.count attribute
Added gen_ai.request.temperature, gen_ai.request.max_tokens, gen_ai.request.max_steps attributes
Added gen_ai.cache.input_tokens and gen_ai.cache.read_input_tokens
Added gen_ai.cost_usd via calculateCost()
Added wrapStreamWithMetrics() -- wraps the async generator with a child span (neurolink.provider.stream.consumption) that records TTFC, chunk count, total content size, and stream duration
Added gen_ai.stream.error_recovery events for fallback scenarios

GenerationHandler:

Added gen_ai.message.total_chars, gen_ai.messages_preview with system/user message previews
Added gen_ai.tool.call and gen_ai.tool.result events in onStepFinish
Added cache token attributes and cost calculation in both primary and fallback paths

neurolink.ts:

Added gen_ai.input_preview on generate span
Wrapped mem0 search/store in neurolink.mem0.search / neurolink.mem0.store spans
Wrapped conversation store in neurolink.conversation.store spans (both MCP and direct paths)
Wrapped conversation fetch in neurolink.conversation.fetch span
Wrapped budget check in neurolink.context.budget_check span with per-component token breakdown (M16)
Wrapped context compaction in neurolink.context.compact span
Added neurolink.generate.path attribute ("mcp" or "direct")
Added provider selection chain: gen_ai.provider.candidates, gen_ai.provider.selected, gen_ai.provider.fallback_count, gen_ai.provider.fallback events (H27)

ConversationMemoryManager:

Added neurolink.memory.initialize, neurolink.memory.storeTurn, neurolink.memory.checkAndSummarize, neurolink.memory.buildContext, neurolink.memory.getSession spans with full attributes
Removed unused estimateTokens() private method

providerRetry:

Wrapped retry loop in neurolink.provider.retry child span (C15)
Added retry.reason classification: rate_limit, timeout, server_error, connection_refused, connection_reset, unknown (M17)
Added per-attempt events, backoff tracking, and error recording

MCP modules:

externalServerManager.ts: Added neurolink.mcp.server.start, neurolink.mcp.server.stop, neurolink.mcp.server.restart, neurolink.mcp.server.healthCheck spans
mcpClientFactory.ts: Wrapped createClient in neurolink.mcp.createClient span with protocol version, transport type, duration attributes
mcpCircuitBreaker.ts: Added circuit.state_change and circuit.half_open_test OTel events
toolDiscoveryService.ts: Added OTel spans for tool discovery operations

Files Changed:

src/lib/core/baseProvider.ts (+178 lines)
src/lib/core/modules/GenerationHandler.ts (+130 lines)
src/lib/neurolink.ts (+1029/-529 lines)
src/lib/core/conversationMemoryManager.ts (+369 lines)
src/lib/utils/providerRetry.ts (+214 lines)
src/lib/mcp/externalServerManager.ts (+574 lines)
src/lib/mcp/mcpClientFactory.ts (+449 lines)
src/lib/mcp/mcpCircuitBreaker.ts (+27 lines)
src/lib/mcp/toolDiscoveryService.ts (+367 lines)

Verification: PASS

P1-5: Circuit Breaker Timer Leak + Signal Handler Leak + Debug Artifact

Issue: Three separate resource leaks / cleanup issues:

Circuit breaker cleanup timers were never destroyed during shutdown, leaking setInterval timers.
Process signal handlers (SIGINT, SIGTERM, beforeExit) were registered as anonymous arrow functions, making them impossible to remove during shutdown.
A hardcoded debug filter for "SuccessRateSRByTime" / "juspay-analytics" tool was left in the generateTextInternal() method's logging.

Root Cause:

globalCircuitBreakerManager.destroyAll() was never called in ExternalServerManager.shutdown().
Anonymous arrow functions passed to process.on() cannot be referenced for process.removeListener().
Debug artifact from development was not removed before merge.

Fix Applied:

Added globalCircuitBreakerManager.destroyAll() call in ExternalServerManager.shutdown().
Stored the shutdown handler as a named instance field (private shutdownHandler = () => { void this.shutdown(); }), used it for process.on() registration, and added matching process.removeListener() calls in shutdown().
Removed the hardcoded targetTool debug filter block from neurolink.ts.

Files Changed:

src/lib/mcp/externalServerManager.ts:
- Lines ~224-226: Added shutdownHandler field
- Lines ~262-264: Use this.shutdownHandler for signal registration
- Lines ~1595-1603: Added process.removeListener() calls and globalCircuitBreakerManager.destroyAll()
src/lib/neurolink.ts (lines ~3752-3765 removed debug artifact)

Verification: PASS

4. P2 Medium Priority Fixes

P2-1: Extract resolveTools() to BaseProvider (Eliminate 14 Copies)

Issue: Every provider had a duplicated 3-4 line pattern for tool resolution:

const shouldUseTools = !options.disableTools && this.supportsTools();
const tools = shouldUseTools
  ? (options.tools as Record<string, Tool>) || (await this.getAllTools())
  : {};

Root Cause: When providers were developed independently, each copied the same tool resolution logic. No shared method existed in BaseProvider.

Fix Applied: Added a protected resolveTools() method to BaseProvider and replaced the duplicated blocks in all 11 providers that had them.

New Method in BaseProvider:

protected async resolveTools(
  options: StreamOptions | TextGenerationOptions,
): Promise<Record<string, Tool>> {
  const shouldUseTools = !options.disableTools && this.supportsTools();
  return shouldUseTools
    ? (options.tools as Record<string, Tool>) || (await this.getAllTools())
    : {};
}

Providers Updated (14 occurrences across 11 files):

src/lib/providers/anthropic.ts -- Replaced 3-line block with this.resolveTools(options)
src/lib/providers/anthropicBaseProvider.ts -- Same
src/lib/providers/azureOpenai.ts -- Same
src/lib/providers/googleAiStudio.ts -- Same (was 4 lines with separate baseTools variable)
src/lib/providers/googleVertex.ts -- Same (was 4 lines)
src/lib/providers/huggingFace.ts -- Same
src/lib/providers/litellm.ts -- Same
src/lib/providers/mistral.ts -- Same
src/lib/providers/openAI.ts -- Same
src/lib/providers/openRouter.ts -- Same
src/lib/providers/openaiCompatible.ts -- Same

Secondary Change: All providers also updated their toolChoice logic from shouldUseTools ? "auto" : "none" to Object.keys(tools).length > 0 ? "auto" : "none", which is more correct (checks actual tool availability rather than just the configuration flag).

Files Changed:

src/lib/core/baseProvider.ts (lines ~625-637) -- New resolveTools() method
All 11 provider files listed above

Verification: PASS

P2-2: Misc Cleanups (Tracer Name, Dead Code, Unsafe Casts, Debug Artifacts)

Issue: Several small code quality issues across the codebase:

Logger mismatch in httpRetryHandler.ts: Used logger (general) instead of mcpLogger (MCP-specific).
Removed unused Tool type import from 6 provider files (cleaned up after resolveTools() extraction).
Removed unused TransportWithProcessResult type import from mcpClientFactory.ts.
Removed unused estimateTokens() private method from ConversationMemoryManager.
Added unbounded queue protection in HTTPRateLimiter (MAX_QUEUE_SIZE = 1000).
Updated httpRetryHandler.ts documentation to remove ENOTFOUND from the retryable list in the JSDoc comment.

Files Changed:

src/lib/mcp/httpRetryHandler.ts -- Switched logger to mcpLogger (3 occurrences), updated JSDoc
src/lib/mcp/httpRateLimiter.ts -- Added queue size limit
src/lib/mcp/mcpClientFactory.ts -- Removed unused spawn and TransportWithProcessResult imports, added LATEST_PROTOCOL_VERSION import
src/lib/providers/anthropic.ts, anthropicBaseProvider.ts, azureOpenai.ts, huggingFace.ts, litellm.ts, mistral.ts, openAI.ts, openRouter.ts, openaiCompatible.ts -- Removed unused type Tool import
src/lib/core/conversationMemoryManager.ts -- Removed unused estimateTokens() method
src/lib/core/modules/TelemetryHandler.ts -- Minor fix (2 lines)

Verification: PASS

5. Impact Analysis Matrix

Provider Impact

Provider	P1-1 Typed Errors	P1-2 maxRetries:0	P2-1 resolveTools	Other
OpenAI	--	Already had	Yes	Unused import cleanup
Anthropic	Already had	Already had	Yes	Unused import cleanup
AnthropicV2	Already had	Already had	Yes	Unused import cleanup
Azure OpenAI	Added	Added	Yes	--
Google AI Studio	--	Added	Yes	--
Google Vertex	--	Already had	Yes	--
Mistral	Added	Added	Yes	Unused import cleanup
HuggingFace	Added	Added	Yes	Unused import cleanup
LiteLLM	--	Already had	Yes	Unused import cleanup
OpenRouter	--	Already had	Yes	Unused import cleanup
OpenAI Compatible	--	Added	Yes	Unused import cleanup
Ollama	--	N/A (local)	--	--

SDK Path Impact

Fix	generate()	stream()	Both
P0-3 Cost Estimation	Yes	--	--
P1-3 Timeout Composition	--	Yes	--
P1-4 OTel Parity	--	Yes	Converged
P2-1 resolveTools	--	Yes	--
P1-1 Typed Errors	--	--	Both (formatProviderError)
P1-2 maxRetries:0	--	Yes (streamText)	--

MCP Module Impact

Fix	externalServerManager	mcpClientFactory	mcpCircuitBreaker	toolDiscoveryService	httpRetryHandler	httpRateLimiter
P0-1 Double Spawn	--	Yes	--	--	--	--
P0-2 Restart Timer	Yes	--	--	--	--	--
P0-4b Headers	--	Yes	--	--	--	--
P0-4c Validation	--	Yes	--	--	--	--
P1-2 ENOTFOUND	--	--	--	--	Yes	--
P1-4 OTel	Yes	Yes	Yes	Yes	--	--
P1-5 Leaks	Yes	--	Yes (via destroyAll)	--	--	--
P2-2 Cleanups	--	Yes	--	--	Yes	Yes

6. Verification Results Summary

Task ID	Description	Status
#2	FIX-P0-1: Double process spawn in stdio transport	PASS
#3	FIX-P0-2: Restart timer never cleared	PASS
#4	FIX-P0-3: Accurate cost estimation via pricing.ts	PASS
#5	FIX-P0-4: Tool I/O size, SSE/WS headers, validateClientConfig	PASS
#6	FIX-P1-1: Typed errors in Azure/Mistral/HuggingFace	PASS
#7	FIX-P1-2: maxRetries:0 in 5 providers + ENOTFOUND	PASS
#8	FIX-P1-3: Stream timeout composition + abort differentiation	PASS
#9	FIX-P1-4: OTel stream/generate parity	PASS
#10	FIX-P1-5: Circuit breaker timer + signal handler leak + debug artifact	PASS
#11	FIX-P2-1: resolveTools() extraction	PASS
#12	FIX-P2-2: Misc cleanups	PASS

All 11 implementation tasks verified PASS by independent verification agents.

7. Remaining Gaps / Future Work

Out-of-Scope Items Identified During Review

Evaluation/Scoring module has 0 test coverage -- 11 source files (1,822 lines) with no tests. This is a known gap tracked separately.
Stream path cost estimation -- While generate() now has accurate cost via calculateCost(), the stream path records cost only on BaseProvider.generate() spans. Stream consumption spans do not yet include cost because final token counts are only available after stream completion. A future improvement could add cost calculation to the wrapStreamWithMetrics() completion handler.
Redis ConversationMemoryManager OTel parity -- OTel spans were added to the in-memory ConversationMemoryManager, but the Redis implementation should also be checked for equivalent instrumentation.
Provider-specific retry configuration -- Currently all providers share the same MAX_PROVIDER_RETRIES = 2 constant. Some providers (e.g., rate-limited free-tier APIs) might benefit from configurable retry counts.
Ollama provider -- Was not touched by any fixes. Does not have resolveTools() because Ollama has a different streaming architecture. Should be reviewed separately.

Test Coverage Gaps

No unit tests specifically for resolveTools() method behavior.
No unit tests for the new wrapStreamWithMetrics() stream instrumentation wrapper.
No unit tests for abort error differentiation in the stream catch block.
The OTel span assertions in existing tests may not cover all new span attributes.

8. Files Changed Summary

File	Lines Added	Lines Removed	Net
`src/lib/neurolink.ts`	+1029	-529	+500
`src/lib/mcp/externalServerManager.ts`	+574	-392	+182
`src/lib/core/modules/MessageBuilder.ts`	+501	-340	+161
`src/lib/mcp/mcpClientFactory.ts`	+449	-300	+149
`src/lib/core/conversationMemoryManager.ts`	+369	-180	+189
`src/lib/mcp/toolDiscoveryService.ts`	+367	-220	+147
`src/lib/utils/providerRetry.ts`	+214	-86	+128
`src/lib/core/baseProvider.ts`	+178	-18	+160
`src/lib/core/modules/GenerationHandler.ts`	+130	-10	+120
`src/lib/providers/azureOpenai.ts`	+85	-21	+64
`src/lib/core/modules/StreamHandler.ts`	+72	-36	+36
`src/lib/providers/huggingFace.ts`	+70	-36	+34
`src/lib/core/modules/ToolsManager.ts`	+168	-50	+118
`src/lib/providers/mistral.ts`	+62	-21	+41
`src/lib/mcp/mcpCircuitBreaker.ts`	+27	-0	+27
`src/lib/providers/googleVertex.ts`	+15	-16	-1
`src/lib/providers/openAI.ts`	+14	-14	0
`src/lib/mcp/httpRetryHandler.ts`	+11	-7	+4
`src/lib/providers/openRouter.ts`	+11	-13	-2
`src/lib/providers/litellm.ts`	+11	-13	-2
`src/lib/providers/openaiCompatible.ts`	+10	-10	0
`src/lib/providers/anthropic.ts`	+9	-9	0
`src/lib/providers/anthropicBaseProvider.ts`	+9	-9	0
`src/lib/providers/googleAiStudio.ts`	+9	-11	-2
`src/lib/mcp/httpRateLimiter.ts`	+4	-0	+4
`src/lib/core/modules/TelemetryHandler.ts`	+2	-2	0
Total	+2,876	-1,524	+1,352

1. Executive Summary​

2. P0 Bug Fixes (Critical)​

P0-1: Double Process Spawn in stdio Transport​

P0-2: Restart Timer Never Cleared​

P0-3: Inaccurate Cost Estimation (5x Error)​

P0-4a: tool.input_size/output_size Reporting Truncated Length​

P0-4b: SSE/WebSocket Headers Silently Ignored​

P0-4c: validateClientConfig Rejecting Valid HTTP Configs​

3. P1 High Priority Fixes​

P1-1: Typed Errors Missing in Azure/Mistral/HuggingFace​

P1-2: maxRetries:0 Missing from 5 Providers + ENOTFOUND Non-Retryable​

P1-3: Stream Timeout Composition + Abort Differentiation​

P1-4: OTel Stream/Generate Parity​

P1-5: Circuit Breaker Timer Leak + Signal Handler Leak + Debug Artifact​

4. P2 Medium Priority Fixes​

P2-1: Extract resolveTools() to BaseProvider (Eliminate 14 Copies)​

P2-2: Misc Cleanups (Tracer Name, Dead Code, Unsafe Casts, Debug Artifacts)​

5. Impact Analysis Matrix​

Provider Impact​

SDK Path Impact​

MCP Module Impact​

6. Verification Results Summary​

7. Remaining Gaps / Future Work​

Out-of-Scope Items Identified During Review​

Test Coverage Gaps​

8. Files Changed Summary​

1. Executive Summary

2. P0 Bug Fixes (Critical)

P0-1: Double Process Spawn in stdio Transport

P0-2: Restart Timer Never Cleared

P0-3: Inaccurate Cost Estimation (5x Error)

P0-4a: tool.input_size/output_size Reporting Truncated Length

P0-4b: SSE/WebSocket Headers Silently Ignored

P0-4c: validateClientConfig Rejecting Valid HTTP Configs

3. P1 High Priority Fixes

P1-1: Typed Errors Missing in Azure/Mistral/HuggingFace

P1-2: maxRetries:0 Missing from 5 Providers + ENOTFOUND Non-Retryable

P1-3: Stream Timeout Composition + Abort Differentiation

P1-4: OTel Stream/Generate Parity

P1-5: Circuit Breaker Timer Leak + Signal Handler Leak + Debug Artifact

4. P2 Medium Priority Fixes

P2-1: Extract resolveTools() to BaseProvider (Eliminate 14 Copies)

P2-2: Misc Cleanups (Tracer Name, Dead Code, Unsafe Casts, Debug Artifacts)

5. Impact Analysis Matrix

Provider Impact

SDK Path Impact

MCP Module Impact

6. Verification Results Summary

7. Remaining Gaps / Future Work

Out-of-Scope Items Identified During Review

Test Coverage Gaps

8. Files Changed Summary